Upload & Manage Documents

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.

$
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
}

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

$
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"]}'

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

• Ask a Question — query documents using Pyramid Agent
• Run a Compliance Check — verify requirements against your documents