Documents

Documents supply the content AutoSage indexes for grounded retrieval. All endpoints are served under /documents and support API keys or signed-in user sessions.

All endpoints on this page are [User+Key]. API keys need the corresponding documents:read, documents:write, or documents:delete scope.

Endpoints

Method	Path	Description	Auth
`POST`	`/documents/presign`	Create a document and request an upload URL	[User+Key]
`GET`	`/documents/status`	Check processing status	[User+Key]
`GET`	`/documents`	List documents in a knowledge base	[User+Key]
`POST`	`/documents/upload-url`	Ingest one web page	[User+Key]
`POST`	`/documents/upload-url-site`	Discover pages on a site	[User+Key]
`GET`	`/documents/:id`	Get a document	[User+Key]
`GET`	`/documents/:id/download`	Request a download URL	[User+Key]
`DELETE`	`/documents/:id`	Remove a document	[User+Key]
`POST`	`/documents/:id/reprocess`	Process a document again	[User+Key]

Request an upload URL

POST /documents/presign Creates a document in pending_upload and returns a time-limited URL for uploading the raw bytes.

string

required

Knowledge base that will receive the document.

string

required

Tenant that owns the knowledge base. It must match the knowledge base’s tenant.

string

required

Original filename, including its extension.

string

required

MIME type of the uploaded file.

number

required

File size in bytes. AutoSage checks document and storage quotas before returning an upload URL.

curl -X POST "$AUTOSAGE_URL/documents/presign" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_id": "KB_ID",
    "tenant_id": "TENANT_ID",
    "filename": "handbook.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 482913
  }'

The response includes document_id, upload_url, s3_key, and expires_at. Treat s3_key as an opaque storage identifier.

Upload the bytes

Upload the file directly to the returned upload_url before it expires:

curl -X PUT "UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @handbook.pdf

Processing starts automatically after the upload completes. No additional API call is required.

Check processing status

GET /documents/status

string

required

Document ID returned by the presign request.

curl "$AUTOSAGE_URL/documents/status?document_id=DOCUMENT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"

The response includes status, is_processing, timestamps, and document metadata.

Status	Meaning
`pending_upload`	Waiting for file bytes.
`queued`	Uploaded and waiting for processing.
`processing`	Being parsed, chunked, embedded, and indexed.
`processed`	Searchable and ready for grounded answers.
`failed`	Processing did not complete.
`deleted`	Removed from active document listings and retrieval.

Poll with backoff until the status is processed or failed. A document you later remove may be reported as deleted. See Document ingestion for the complete lifecycle.

List documents

GET /documents

string

required

Knowledge base whose active documents to list.

curl "$AUTOSAGE_URL/documents?kb_id=KB_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"

Documents that have been removed are excluded.

Ingest one web page

POST /documents/upload-url Fetches one URL, converts its readable content into a document, and queues it for processing.

string

required

Destination knowledge base.

string

required

Owning tenant. It must match the knowledge base’s tenant.

string

required

Page to ingest. AutoSage adds https:// when the scheme is omitted.

curl -X POST "$AUTOSAGE_URL/documents/upload-url" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kb_id": "KB_ID",
    "tenant_id": "TENANT_ID",
    "url": "https://docs.example.com/getting-started"
  }'

Discover site URLs

POST /documents/upload-url-site Discovers up to 25 pages from a site. This endpoint returns URLs; ingest selected pages individually with /documents/upload-url.

string

required

Knowledge base used for access validation.

string

required

Owning tenant.

string

required

Site root to crawl.

boolean

Include matching subdomains. Defaults to false.

Get a document

GET /documents/:id Returns metadata for one document, including its processing state.

curl "$AUTOSAGE_URL/documents/DOCUMENT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"

Request a download URL

GET /documents/:id/download Returns a time-limited download_url for the original file, plus filename and expires_at.

Remove a document

DELETE /documents/:id Removes the document from search and begins cleanup of its stored file and indexed content.

Removing a document is destructive. Clients should stop presenting it as searchable as soon as the request succeeds.

Reprocess a document

POST /documents/:id/reprocess Queues an existing document for processing again. This is useful after a failed status. Removed documents and derived text documents cannot be reprocessed independently.

Full request and response schemas are available in the interactive explorer at /swagger on the API host.

Next steps

Upload guide

Implement the presigned upload flow in your application.

Ingestion lifecycle

Understand processing stages, statuses, and quotas.

Knowledge bases

Manage the knowledge base that owns these documents.

Retrieval lifecycle

See how processed content grounds answers.

Get started

Core concepts

Lifecycles

Guides

API reference

Endpoints

Request an upload URL

Upload the bytes

Check processing status

List documents

Ingest one web page

Discover site URLs

Get a document

Request a download URL

Remove a document

Reprocess a document

Next steps

Upload guide

Ingestion lifecycle

Knowledge bases

Retrieval lifecycle

​Endpoints

​Request an upload URL

​Upload the bytes

​Check processing status

​List documents

​Ingest one web page

​Discover site URLs

​Get a document

​Request a download URL

​Remove a document

​Reprocess a document

​Next steps

Upload guide

Ingestion lifecycle

Knowledge bases

Retrieval lifecycle

Endpoints

Request an upload URL

Upload the bytes

Check processing status

List documents

Ingest one web page

Discover site URLs

Get a document

Request a download URL

Remove a document

Reprocess a document

Next steps