Getting Started

Getting Started

Make your first API call in under 5 minutes
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