Documents

Upload, process, and manage knowledge documents

Documents

Upload, process, and manage knowledge documents

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}

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)

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}

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)

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

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	}

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

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

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

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	}

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

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

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