Skip to main content
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

MethodPathDescriptionAuth
POST/documents/presignCreate a document and request an upload URL[User+Key]
GET/documents/statusCheck processing status[User+Key]
GET/documentsList documents in a knowledge base[User+Key]
POST/documents/upload-urlIngest one web page[User+Key]
POST/documents/upload-url-siteDiscover pages on a site[User+Key]
GET/documents/:idGet a document[User+Key]
GET/documents/:id/downloadRequest a download URL[User+Key]
DELETE/documents/:idRemove a document[User+Key]
POST/documents/:id/reprocessProcess 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.
​
kb_id
string
required
Knowledge base that will receive the document.
​
tenant_id
string
required
Tenant that owns the knowledge base. It must match the knowledge base’s tenant.
​
filename
string
required
Original filename, including its extension.
​
mime_type
string
required
MIME type of the uploaded file.
​
size_bytes
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
​
document_id
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.
StatusMeaning
pending_uploadWaiting for file bytes.
queuedUploaded and waiting for processing.
processingBeing parsed, chunked, embedded, and indexed.
processedSearchable and ready for grounded answers.
failedProcessing did not complete.
deletedRemoved 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
​
kb_id
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.
​
kb_id
string
required
Destination knowledge base.
​
tenant_id
string
required
Owning tenant. It must match the knowledge base’s tenant.
​
url
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.
​
kb_id
string
required
Knowledge base used for access validation.
​
tenant_id
string
required
Owning tenant.
​
url
string
required
Site root to crawl.
​
include_subdomains
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.