Skip to navigation
How-To Guides

Upload & Manage Documents

Upload files, trigger processing, and manage your knowledge base

Before you begin

  • You have an API key (pai_test_* or pai_live_*)
  • You have at least one project created (Create a Project)
  • Feature api.documents is enabled for your organization

Upload a document (3-step flow)

Document upload uses presigned URLs so your files go directly to storage without passing through the API server.

1

Reserve an upload slot

Tell the API what file you’re uploading. You’ll get back a presigned URL for direct upload.

curl -X POST https://api-staging.pyramid-ai.com/api/v2/documents \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "safety-manual.pdf",
    "content_type": "application/pdf",
    "size_bytes": 2048576,
    "project_id": "YOUR_PROJECT_ID"
  }'
{
  "success": true,
  "data": {
    "id": "doc_xyz789",
    "status": "uploading",
    "upload": {
      "url": "https://storage.supabase.co/...",
      "method": "PUT",
      "headers": {
        "Content-Type": "application/pdf"
      },
      "expires_at": "2026-05-20T10:15:00Z"
    }
  },
  "request_id": "..."
}

Save the id and the upload.url.

2

Upload the file to storage

Use the presigned URL from step 1 to upload your file directly. No authorization header needed — the URL itself is the grant.

curl -X PUT "PRESIGNED_URL_FROM_STEP_1" \
  -H "Content-Type: application/pdf" \
  --data-binary @safety-manual.pdf

The presigned URL expires after 15 minutes. If it expires, reserve a new upload slot.

3

Trigger processing

Once the file is uploaded, tell the API to start processing it into searchable knowledge.

curl -X POST https://api-staging.pyramid-ai.com/api/v2/documents/process \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["doc_xyz789"]}'

You can pass multiple document IDs to process several files at once.

Check document status

After triggering processing, poll the document to track its progress:

curl https://api-staging.pyramid-ai.com/api/v2/documents/doc_xyz789 \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE"
{
  "success": true,
  "data": {
    "id": "doc_xyz789",
    "file_name": "safety-manual.pdf",
    "status": "ready",
    "project_id": "YOUR_PROJECT_ID",
    "created_at": "2026-05-20T10:00:00Z"
  },
  "request_id": "..."
}

Document status progresses through: uploading → uploaded → processing → ready. A document is queryable once it reaches ready.

List documents

# All documents in a project
curl "https://api-staging.pyramid-ai.com/api/v2/documents?project_id=YOUR_PROJECT_ID" \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE"
# Filter by status
curl "https://api-staging.pyramid-ai.com/api/v2/documents?project_id=YOUR_PROJECT_ID&status=ready" \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE"

Delete documents

Remove one or more documents in a single call:

curl -X DELETE https://api-staging.pyramid-ai.com/api/v2/documents \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["doc_xyz789"]}'

This removes the document, its storage file, and all associated chunks and embeddings.

What’s next