For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Get API Key
GuidesAPI Reference
GuidesAPI Reference
  • Getting Started
    • Introduction
    • Getting Started
    • Authentication
    • Rate Limits
    • Error Handling
  • Concepts
    • Projects & Documents
    • Document Processing
    • Knowledge & Search
    • Compliance Checking
    • Environments & Keys
    • Streaming & Async
  • How-To Guides
    • Manage Projects
    • Upload & Manage Documents
    • Query Your Knowledge Base
    • Run Compliance Checks
    • View Your Organization
Get API Key
LogoLogo
On this page
  • Response envelope
  • Next steps
Getting Started

Getting Started

Make your first API call in under 5 minutes
Was this page helpful?
Edit this page
Previous

Authentication

API key management, environments, and security
Next
Built with
1

Get your API key

API keys are provisioned by your Pyramid AI account manager during pilot onboarding. You’ll receive a key with the prefix:

  • pai_live_* for production
  • pai_test_* for staging/sandbox

Store your API key securely. It is shown only once at creation time and cannot be retrieved later. If lost, request a key rotation from your admin.

2

Verify your connection

Test that your key works by calling the organization endpoint:

$curl https://api-staging.pyramid-ai.com/api/v2/organization \
>  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE"

A successful response:

1{
2  "success": true,
3  "data": {
4    "id": "org_abc123",
5    "name": "Your Organization"
6  },
7  "request_id": "550e8400-e29b-41d4-a716-446655440000"
8}
3

Create a project

Projects are containers for your documents and knowledge base.

$curl -X POST https://api-staging.pyramid-ai.com/api/v2/projects \
>  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE" \
>  -H "Content-Type: application/json" \
>  -d '{"name": "My First Project", "description": "Testing the API"}'
4

Upload a document

Document upload is a 3-step process: reserve, upload bytes, then trigger processing.

$# Step 1: Reserve an upload slot
$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": "report.pdf",
>    "content_type": "application/pdf",
>    "size_bytes": 1048576,
>    "project_id": "YOUR_PROJECT_ID"
>  }'
$
$# Step 2: Upload the file to the presigned URL from step 1
$curl -X PUT "PRESIGNED_URL_FROM_STEP_1" \
>  -H "Content-Type: application/pdf" \
>  --data-binary @report.pdf
$
$# Step 3: Trigger processing
$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": ["DOCUMENT_ID_FROM_STEP_1"]}'
5

Ask a question

Once your documents are processed, query your knowledge base:

$curl -X POST https://api-staging.pyramid-ai.com/api/v2/agent/query \
>  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "project_id": "YOUR_PROJECT_ID",
>    "query": "What are the main findings in the report?"
>  }'
1{
2  "success": true,
3  "data": {
4    "answer": "Based on the project documents...",
5    "sources": [
6      {
7        "id": "chunk_abc",
8        "title": "report.pdf",
9        "relevance": 0.95
10      }
11    ],
12    "model": "gpt-4.1",
13    "usage": {
14      "prompt_tokens": 1200,
15      "completion_tokens": 350
16    }
17  },
18  "request_id": "..."
19}

Response envelope

Every API response uses a consistent envelope:

1// Success
2{
3  "success": true,
4  "data": { ... },
5  "request_id": "uuid"
6}
7
8// Error
9{
10  "success": false,
11  "error": {
12    "code": "VALIDATION_ERROR",
13    "message": "project_id is required"
14  },
15  "request_id": "uuid"
16}

The request_id is also returned in the X-Request-Id response header. Include it when contacting support.

Next steps

Manage Projects

Create, list, update, and organize your knowledge projects

Upload Documents

Upload files and build your searchable knowledge base

Query Knowledge

Ask questions, run batch queries, and export results

Compliance Checks

Verify requirements with AI-powered verdicts

  • Authentication — API key details, environments, and rotation
  • Error Handling — error codes and retry strategies