> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://documents.pyramid-ai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://documents.pyramid-ai.com/_mcp/server.

# Getting Started

#### 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

> **Warning**
>
> 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.

#### Verify your connection

Test that your key works by calling the organization endpoint:

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

A successful response:

```json
{
  "success": true,
  "data": {
    "id": "org_abc123",
    "name": "Your Organization"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### Create a project

Projects are containers for your documents and knowledge base.

```bash
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"}'
```

#### Upload a document

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

```bash
# 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"]}'
```

#### Ask a question

Once your documents are processed, query your knowledge base:

```bash
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?"
  }'
```

```json
{
  "success": true,
  "data": {
    "answer": "Based on the project documents...",
    "sources": [
      {
        "id": "chunk_abc",
        "title": "report.pdf",
        "relevance": 0.95
      }
    ],
    "model": "gpt-4.1",
    "usage": {
      "prompt_tokens": 1200,
      "completion_tokens": 350
    }
  },
  "request_id": "..."
}
```

## Response envelope

Every API response uses a consistent envelope:

```json
// Success
{
  "success": true,
  "data": { ... },
  "request_id": "uuid"
}

// Error
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "project_id is required"
  },
  "request_id": "uuid"
}
```

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

## Next steps

#### [Manage Projects](/howto/projects)

Create, list, update, and organize your knowledge projects

#### [Upload Documents](/howto/documents)

Upload files and build your searchable knowledge base

#### [Query Knowledge](/howto/agent)

Ask questions, run batch queries, and export results

#### [Compliance Checks](/howto/check)

Verify requirements with AI-powered verdicts

* [Authentication](/authentication) — API key details, environments, and rotation
* [Error Handling](/error-handling) — error codes and retry strategies