Documents | Pyramid AI | Developer Docs

Documents are files uploaded to a project. Once processed, the AI can search through them to answer questions and verify compliance. See Document Processing for a detailed explanation of the upload flow.

POST /api/v2/documents

Reserve a document upload slot. Step 1 of the upload flow. Returns a presigned URL for direct file upload to storage.

Authentication: Bearer token required

Request body:

Field	Type	Required	Description
`file_name`	string	Yes	File name (no path separators). 1–500 characters
`content_type`	string	Yes	MIME type (e.g., `application/pdf`, `application/msword`)
`size_bytes`	integer	Yes	File size in bytes (max 500 MB)
`project_id`	uuid	No	Project to associate with. Omit for org-level documents

Example request:

$ 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-Management-Plan-2026.pdf",
>     "content_type": "application/pdf",
>     "size_bytes": 2048576,
>     "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f"
>   }'

Example response 201 Created:

1 {
2   "success": true,
3   "data": {
4     "id": "9d11d31d-17ce-4b9f-8c13-63d7058f5fd3",
5     "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
6     "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
7     "file_name": "Safety-Management-Plan-2026.pdf",
8     "content_type": "application/pdf",
9     "size_bytes": null,
10     "status": "awaiting_upload",
11     "chunk_count": null,
12     "error_message": null,
13     "created_at": "2026-05-22T10:00:00Z",
14     "updated_at": "2026-05-22T10:00:00Z",
15     "upload": {
16       "url": "https://storage.supabase.co/...",
17       "method": "PUT",
18       "recommended_content_type": "application/pdf",
19       "expires_at": "2026-05-22T12:00:00Z"
20     }
21   },
22   "request_id": "..."
23 }

After receiving the response, upload your file directly to upload.url:

$ curl -X PUT "UPLOAD_URL_FROM_RESPONSE" \
>   -H "Content-Type: application/pdf" \
>   --data-binary @Safety-Management-Plan-2026.pdf

The upload URL expires after approximately 2 hours. If it expires before you upload, call this endpoint again to get a fresh URL.

POST /api/v2/documents/process

Trigger processing for uploaded documents. Step 2 of the upload flow. After uploading file bytes to the presigned URL, call this to start text extraction, chunking, and indexing.

Authentication: Bearer token required

Request body:

Field	Type	Required	Description
`document_ids`	uuid[]	Yes	Array of document IDs to process (1–100)

Example request:

$ 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": ["9d11d31d-17ce-4b9f-8c13-63d7058f5fd3"]}'

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "processed": ["9d11d31d-17ce-4b9f-8c13-63d7058f5fd3"],
5     "skipped": [],
6     "failed": []
7   },
8   "request_id": "..."
9 }

Field	Type	Description
`processed`	uuid[]	Documents that started processing successfully
`skipped`	object[]	Documents skipped with a `reason` (already processed, wrong state, etc.)
`failed`	object[]	Documents that failed with an `error` and `message`

Skipped reasons:

Reason	Description
`not_found`	Document ID doesn’t exist or belongs to another org
`not_awaiting_upload`	Document already past the upload stage
`upload_not_found`	File bytes not found in storage
`size_mismatch`	Uploaded file size doesn’t match declared `size_bytes`
`content_type_mismatch`	Uploaded file type doesn’t match declared `content_type`

GET /api/v2/documents

List documents with optional filters. Supports pagination.

Authentication: Bearer token required

Query parameters:

Parameter	Type	Default	Description
`project_id`	uuid	—	Filter by project
`document_ids`	string	—	Comma-separated list of document UUIDs
`status`	string	—	Filter by status: `awaiting_upload`, `processing`, `ready`, `completed`, `failed`
`limit`	integer	50	Maximum results per page (max 200)
`offset`	integer	0	Number of results to skip

Example request:

$ curl "https://api.pyramid-ai.com/api/v2/documents?project_id=7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f&status=completed" \
>   -H "Authorization: Bearer pai_live_YOUR_KEY"

Example response 200 OK:

1 {
2   "success": true,
3   "data": [
4     {
5       "id": "9d11d31d-17ce-4b9f-8c13-63d7058f5fd3",
6       "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
7       "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
8       "file_name": "Safety-Management-Plan-2026.pdf",
9       "content_type": "application/pdf",
10       "size_bytes": 2048576,
11       "status": "completed",
12       "chunk_count": 85,
13       "error_message": null,
14       "created_at": "2026-05-22T10:00:00Z",
15       "updated_at": "2026-05-22T10:05:30Z"
16     }
17   ],
18   "request_id": "...",
19   "pagination": {
20     "limit": 50,
21     "offset": 0,
22     "total": 1
23   }
24 }

GET /api/v2/documents/{id}/download

Get a presigned download URL for a document. Returns a short-lived URL (10-minute expiry) for downloading the original source file. Use this to trace AI-generated citations back to the source document — critical for compliance audit trails.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Document ID

Example request:

$ curl https://api.pyramid-ai.com/api/v2/documents/9d11d31d-17ce-4b9f-8c13-63d7058f5fd3/download \
>   -H "Authorization: Bearer pai_live_YOUR_KEY"

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "document_id": "9d11d31d-17ce-4b9f-8c13-63d7058f5fd3",
5     "file_name": "Safety-Management-Plan-2026.pdf",
6     "content_type": "application/pdf",
7     "size_bytes": 2048576,
8     "download_url": "https://storage.supabase.co/object/sign/uploads/orgs/...?token=...",
9     "expires_at": "2026-05-22T10:10:00Z"
10   },
11   "request_id": "..."
12 }

Response fields:

Field	Type	Description
`document_id`	uuid	The document this download URL is for
`file_name`	string	Original file name
`content_type`	string	MIME type of the file
`size_bytes`	integer \| null	File size in bytes
`download_url`	string	Presigned URL — use to download the file directly
`expires_at`	string	When the URL expires (ISO 8601). Generate a new one if expired

The download URL expires after approximately 10 minutes. If it expires, call this endpoint again to get a fresh URL.

Error responses:

Status	Code	When
`404`	`NOT_FOUND`	Document doesn’t exist, belongs to another org, or file is not in storage

GET /api/v2/documents/{id}

Get details for a single document, including its processing status.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Document ID

Example request:

$ curl https://api.pyramid-ai.com/api/v2/documents/9d11d31d-17ce-4b9f-8c13-63d7058f5fd3 \
>   -H "Authorization: Bearer pai_live_YOUR_KEY"

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "id": "9d11d31d-17ce-4b9f-8c13-63d7058f5fd3",
5     "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
6     "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
7     "file_name": "Safety-Management-Plan-2026.pdf",
8     "content_type": "application/pdf",
9     "size_bytes": 2048576,
10     "status": "completed",
11     "chunk_count": 85,
12     "error_message": null,
13     "created_at": "2026-05-22T10:00:00Z",
14     "updated_at": "2026-05-22T10:05:30Z"
15   },
16   "request_id": "..."
17 }

DELETE /api/v2/documents

Delete one or more documents by ID. The AI will no longer reference these documents.

Authentication: Bearer token required

Request body:

Field	Type	Required	Description
`document_ids`	uuid[]	Yes	Array of document IDs to delete (1–100)

Example request:

$ curl -X DELETE https://api.pyramid-ai.com/api/v2/documents \
>   -H "Authorization: Bearer pai_live_YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"document_ids": ["9d11d31d-17ce-4b9f-8c13-63d7058f5fd3"]}'

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "deleted": ["9d11d31d-17ce-4b9f-8c13-63d7058f5fd3"]
5   },
6   "request_id": "..."
7 }

Error responses:

Status	Code	When
`403`	`FORBIDDEN`	One or more document IDs belong to a different organization

Document fields (all endpoints):

Field	Type	Description
`id`	uuid	Unique document identifier
`org_id`	string	Organization the document belongs to
`project_id`	uuid \| null	Project the document is associated with
`file_name`	string	Original file name
`content_type`	string	MIME type (e.g., `application/pdf`)
`size_bytes`	integer \| null	File size in bytes
`status`	string	Processing status: `awaiting_upload`, `processing`, `completed`, `ready`, `failed`
`chunk_count`	integer \| null	Number of searchable chunks created from this document
`error_message`	string \| null	Error details if status is `failed`
`created_at`	string	When the document was created (ISO 8601)
`updated_at`	string	When the document was last modified (ISO 8601)