Use the Document Ingestion API to upload documents to an Airgentic service from an external system. Uploaded documents can be optionally indexed for search and/or handed off to a customer-defined processor script for further handling.

This is the programmatic equivalent of the Upload Documents screen.

Before You Start

You need:

• Your account ID
• Your service ID
• A Document Ingestion API key created on the Security screen
• A document to upload that is CSV, PDF, Word, or HTML, no larger than 500 MB

The API key must be passed in the api-key request header.

Endpoint

Use the following endpoint:

POST https://admin.airgentic.com/api/accounts/{account_id}/services/{service_id}/document-ingestions

The request body must be multipart/form-data.

Path Parameters

Request Header

Form Fields

visibility controls where the file is stored — public files are saved to the same location as the Public Documents tab on the Upload Documents screen, private files are saved to the Secure Documents location.

Example Request

curl -X POST \
  -H "api-key: <API Key>" \
  -F "file=@/path/to/fitment.csv" \
  -F "filename=fitment.csv" \
  -F "mime_type=text/csv" \
  -F "visibility=private" \
  -F "index=false" \
  -F "processor_id=fitment_ingestor" \
  "https://admin.airgentic.com/api/accounts/<account ID>/services/<service ID>/document-ingestions"

To upload a public PDF and rebuild the search index for the service:

curl -X POST \
  -H "api-key: <API Key>" \
  -F "file=@/path/to/handbook.pdf" \
  -F "filename=handbook.pdf" \
  -F "mime_type=application/pdf" \
  -F "visibility=public" \
  -F "index=true" \
  "https://admin.airgentic.com/api/accounts/<account ID>/services/<service ID>/document-ingestions"

Response Format

On success the API returns 201 Created with a JSON body describing the ingestion job:

{
  "ingestion_id": "8b4d6c57-8b5a-4b1d-a442-6a85e7e3958c",
  "account_id": "your-account",
  "service_id": "your-service",
  "processor_id": "fitment_ingestor",
  "processor_invoked": true,
  "filename": "fitment.csv",
  "mime_type": "text/csv",
  "visibility": "private",
  "indexed": false,
  "file_size_bytes": 14238,
  "status": "completed"
}

Response Fields

Processor Scripts

The optional processor_id field lets you trigger a customer-defined Python script after the file has been saved to disk. This is useful for transforming the upload into a different format, loading rows into another system, or enriching it before downstream use.

How to set up a processor

1. Create a file in your service's config directory:

text conf/<account_id>/<service_id>/<processor_id>.py

For example, processor_id=fitment_ingestor maps to conf/centuryyuasa/centurybatteries/fitment_ingestor.py.

1. Make the script accept the document path as the first command-line argument:

```python
import sys

def main(document_path: str) -> None:
print(f"Got document: {document_path}")

if name == "main":
main(sys.argv[1])
```

1. Reference the processor by its filename (without the .py extension) in the processor_id form field.

Execution model

• The script is executed as a separate subprocess using the same Python interpreter as the admin console.
• It runs from a daemon thread, so the API responds immediately — processor_invoked: true only confirms that the subprocess was started, not that it has finished.
• Standard output and standard error from the script are captured and logged to the admin console, along with the script's return code.
• The script has a default timeout of 30 minutes.

Validation rules

• processor_id must contain only letters, digits, and underscores (^[A-Za-z0-9_]+$).
• The matching .py file must already exist in the service's config directory before the upload is sent. If it does not, the request fails with 404 Not Found and the document is not saved.

Common Errors

Notes

• Uploads are streamed to disk, so very large files do not need to be buffered in memory by the client.
• An ingestion job is created in Airgentic for every successful upload, regardless of whether indexing or a processor was requested. The ingestion_id is the canonical reference for that job.
• Setting index=true triggers the same indexing pipeline used by the Upload Documents screen. Indexing runs asynchronously — status: "processing" in the response means the indexing job has been queued, not that it has finished.
• The processor script runs after the file is saved and after indexing has been kicked off (when requested). A failure inside the processor does not change the ingestion status returned by the API; check the admin console logs for return codes and output.

See Also

• Security — Generate and manage the Document Ingestion API key
• Upload Documents — Upload documents interactively from the admin console
• Analytics API — The other Airgentic public API