Document Processing

Overview

Getting a document into Pyramid AI is a three-step process. This design keeps uploads fast and reliable — even for large files — by separating the upload from the processing.

┌─────────────┐      ┌──────────────┐      ┌─────────────────┐
│  1. Reserve  │ ───> │  2. Upload   │ ───> │  3. Process     │
│  (API call)  │      │  (direct PUT)│      │  (API call)     │
└─────────────┘      └──────────────┘      └─────────────────┘
    Returns:              File goes           Starts:
    - document_id         directly to         - Text extraction
    - upload_url          cloud storage       - Chunking
    - expiry time                             - Indexing

Step 1: Reserve an upload slot

Tell the API you’re about to upload a file. You provide the file name, type, and size. The API returns a presigned upload URL — a temporary, secure link where you’ll send the actual file.

$
curl -X POST https://api.pyramid-ai.com/api/v2/documents \
>
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "file_name": "safety-plan.pdf",
>
    "content_type": "application/pdf",
>
    "size_bytes": 2048576,
>
    "project_id": "YOUR_PROJECT_ID"
>
  }'

Response:

1
{
2
  "success": true,
3
  "data": {
4
    "id": "doc_abc123",
5
    "status": "awaiting_upload",
6
    "upload": {
7
      "url": "https://storage.supabase.co/...",
8
      "method": "PUT",
9
      "recommended_content_type": "application/pdf",
10
      "expires_at": "2026-05-22T14:00:00Z"
11
    }
12
  }
13
}

Why presigned URLs?

The file goes directly from your system to cloud storage — it never passes through the Pyramid API server. This means:

• No file size limits from the API layer (Vercel’s 4.5 MB body limit is bypassed)
• Faster uploads — direct connection to storage
• More reliable — fewer hops means fewer failure points

Step 2: Upload the file

Send the actual file bytes to the presigned URL using a PUT request. This is a direct upload to cloud storage — no API key needed (the URL itself contains the authorization).

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

In code (JavaScript)

1
const file = document.getElementById('fileInput').files[0];
2
3
await fetch(uploadUrl, {
4
  method: 'PUT',
5
  headers: { 'Content-Type': file.type },
6
  body: file,
7
});

In code (Python)

1
with open('safety-plan.pdf', 'rb') as f:
2
    requests.put(
3
        upload_url,
4
        data=f,
5
        headers={'Content-Type': 'application/pdf'}
6
    )

Step 3: Trigger processing

Once the file is uploaded, tell the API to start processing it. You can submit multiple document IDs at once.

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

Response:

1
{
2
  "success": true,
3
  "data": {
4
    "processed": ["doc_abc123"],
5
    "skipped": [],
6
    "failed": []
7
  }
8
}

What happens during processing

Behind the scenes, the processing pipeline does the following:

Checking processing status

Poll the document endpoint to check when processing is complete:

$
curl https://api.pyramid-ai.com/api/v2/documents/doc_abc123 \
>
  -H "Authorization: Bearer pai_live_YOUR_KEY"

Watch the status field:

Error handling

Common processing failures:

Batch uploads

For uploading many files at once, repeat the reserve → upload → process cycle for each file, then call process with all document IDs:

$
# Reserve 3 files, upload each one, then process all at once
$
curl -X POST https://api.pyramid-ai.com/api/v2/documents/process \
>
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "document_ids": ["doc_1", "doc_2", "doc_3"]
>
  }'

This is more efficient than processing one at a time, as the pipeline can parallelize the work.