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"
>  }'
1{
2  "success": true,
3  "data": {
4    "id": "doc_xyz789",
5    "status": "uploading",
6    "upload": {
7      "url": "https://storage.supabase.co/...",
8      "method": "PUT",
9      "headers": {
10        "Content-Type": "application/pdf"
11      },
12      "expires_at": "2026-05-20T10:15:00Z"
13    }
14  },
15  "request_id": "..."
16}

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"
1{
2  "success": true,
3  "data": {
4    "id": "doc_xyz789",
5    "file_name": "safety-manual.pdf",
6    "status": "ready",
7    "project_id": "YOUR_PROJECT_ID",
8    "created_at": "2026-05-20T10:00:00Z"
9  },
10  "request_id": "..."
11}

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