> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://documents.pyramid-ai.com/api-reference/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://documents.pyramid-ai.com/_mcp/server. # API Reference ## Docs - [Organizations](https://documents.pyramid-ai.com/api-reference/organizations.md): Retrieve organization details for the authenticated API key - [Projects](https://documents.pyramid-ai.com/api-reference/projects.md): Create and manage knowledge projects - [Documents](https://documents.pyramid-ai.com/api-reference/documents.md): Upload, process, and manage knowledge documents - [Agent](https://documents.pyramid-ai.com/api-reference/agent.md): Single-shot queries, multi-turn chat, and batch processing - [Check](https://documents.pyramid-ai.com/api-reference/check.md): Compliance verification and analysis runs ## API Docs - API Explorer > Agent [Export batch results as CSV](https://documents.pyramid-ai.com/api-reference/api-explorer/agent/export-batch-csv.md) - API Explorer > Agent [Get a batch with results](https://documents.pyramid-ai.com/api-reference/api-explorer/agent/get-batch.md) - API Explorer > Agent [List Agent batch queries](https://documents.pyramid-ai.com/api-reference/api-explorer/agent/list-batches.md) - API Explorer > Agent [Create an Agent batch query](https://documents.pyramid-ai.com/api-reference/api-explorer/agent/create-batch.md) - API Explorer > Agent [Single-shot Q&A over project, org, or Open Library knowledge](https://documents.pyramid-ai.com/api-reference/api-explorer/agent/query-agent.md) - API Explorer > Agent [Chat with the Agent over project, org, or Open Library knowledge](https://documents.pyramid-ai.com/api-reference/api-explorer/agent/chat.md) - API Explorer > Check [List requirements for a check run](https://documents.pyramid-ai.com/api-reference/api-explorer/check/get-check-run-requirements.md) - API Explorer > Check [Get a check run with full results](https://documents.pyramid-ai.com/api-reference/api-explorer/check/get-check-run.md) - API Explorer > Check [Trigger processing for a check run](https://documents.pyramid-ai.com/api-reference/api-explorer/check/trigger-check-run.md) - API Explorer > Check [List compliance check runs](https://documents.pyramid-ai.com/api-reference/api-explorer/check/list-check-runs.md) - API Explorer > Check [Create a compliance check run](https://documents.pyramid-ai.com/api-reference/api-explorer/check/create-check-run.md) - API Explorer > Check [Verify a single compliance requirement](https://documents.pyramid-ai.com/api-reference/api-explorer/check/verify-requirement.md) - API Explorer > Documents [Get a presigned download URL for a document](https://documents.pyramid-ai.com/api-reference/api-explorer/documents/get-document-download-url.md) - API Explorer > Documents [Get a document by ID](https://documents.pyramid-ai.com/api-reference/api-explorer/documents/get-document.md) - API Explorer > Documents [Trigger processing for uploaded documents](https://documents.pyramid-ai.com/api-reference/api-explorer/documents/process-documents.md) - API Explorer > Documents [List documents](https://documents.pyramid-ai.com/api-reference/api-explorer/documents/list-documents.md) - API Explorer > Documents [Reserve a document upload slot](https://documents.pyramid-ai.com/api-reference/api-explorer/documents/reserve-document-upload.md) - API Explorer > Documents [Delete documents by ID](https://documents.pyramid-ai.com/api-reference/api-explorer/documents/delete-documents.md) - API Explorer > Health [List features enabled for the current API key](https://documents.pyramid-ai.com/api-reference/api-explorer/health/list-enabled-features.md) - API Explorer > Health [Health / ping](https://documents.pyramid-ai.com/api-reference/api-explorer/health/check.md) - API Explorer > Organizations [Get the organization for the current API key](https://documents.pyramid-ai.com/api-reference/api-explorer/organizations/get-current-organization.md) - API Explorer > Projects [Get a project by ID](https://documents.pyramid-ai.com/api-reference/api-explorer/projects/get-project.md) - API Explorer > Projects [Delete a project](https://documents.pyramid-ai.com/api-reference/api-explorer/projects/delete-project.md) - API Explorer > Projects [Update a project](https://documents.pyramid-ai.com/api-reference/api-explorer/projects/update-project.md) - API Explorer > Projects [List Connect projects](https://documents.pyramid-ai.com/api-reference/api-explorer/projects/list-projects.md) - API Explorer > Projects [Create a new Connect project](https://documents.pyramid-ai.com/api-reference/api-explorer/projects/create-project.md) ## OpenAPI Specification The raw OpenAPI 3.1 specification for this API is available at: - [OpenAPI JSON](https://documents.pyramid-ai.com/openapi.json) - [OpenAPI YAML](https://documents.pyramid-ai.com/openapi.yaml) > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://documents.pyramid-ai.com/api-reference/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://documents.pyramid-ai.com/_mcp/server. # API Reference The Pyramid AI API is organized into three services, each serving a distinct purpose: #### Pyramid Connect Projects, documents, uploads, and processing. #### Pyramid Agent Chat, single queries, and batch Q\&A. #### Pyramid Check Compliance verification and analysis runs. ## API groups | Group | Prefix | Description | | ----------------- | ---------------------- | ---------------------------------------------- | | **Agent** | `/api/v2/agent` | Single-shot queries and batch operations | | **Check** | `/api/v2/check` | Compliance verification and analysis runs | | **Documents** | `/api/v2/documents` | Upload, process, and manage documents | | **Organizations** | `/api/v2/organization` | Organization details for the authenticated key | | **Projects** | `/api/v2/projects` | Create and manage knowledge projects | ## Authentication Every request (except `/health`) requires a Bearer token: ```bash curl https://api.pyramid-ai.com/api/v2/projects \ -H "Authorization: Bearer pai_live_YOUR_KEY" ``` See [Authentication](/authentication) for key management details. ## Response format Every response follows the same envelope: **`Success`** ```json title="Success" { "success": true, "data": { ... }, "request_id": "550e8400-e29b-41d4-a716-446655440000" } ``` **`Success with pagination`** ```json title="Success with pagination" { "success": true, "data": [ ... ], "request_id": "...", "pagination": { "limit": 50, "offset": 0, "total": 127 } } ``` **`Error`** ```json title="Error" { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "project_id is required", "field": "project_id" }, "request_id": "..." } ``` The `request_id` is also returned in the `X-Request-Id` header. Always include it when contacting support. ## Common status codes | Status | Meaning | Action | | ------ | ---------------- | ----------------------------------------- | | `200` | Success | Process the response | | `201` | Created | Resource created successfully | | `204` | No Content | Deletion successful | | `400` | Validation Error | Fix the request body/params | | `401` | Unauthorized | Check your API key | | `403` | Forbidden | Feature not enabled or wrong org | | `404` | Not Found | Resource doesn't exist | | `409` | Conflict | Duplicate or conflicting state | | `429` | Rate Limited | Wait and retry (see `Retry-After` header) | | `500` | Server Error | Retry with exponential backoff | ## Using the interactive explorer The endpoints below include a built-in playground. To test: 1. Enter your API key in the **Authorization** field (use `Bearer pai_test_*` for staging) 2. Fill in the required parameters 3. Click **Send** to make a live request > **Warning** > > The explorer sends real requests to the server you select. Use a `pai_test_*` key to avoid affecting production data. ## Versioning All endpoints are under `/api/v2`. Breaking changes will increment the version number. Non-breaking additions (new optional fields, new endpoints) are added without a version bump.