Projects | Pyramid AI | Developer Docs

Projects are top-level containers that group related documents together. Every document, query, and compliance check is scoped to a project.

POST /api/v2/projects

Creates a new empty project.

Authentication: Bearer token required

Request body:

Field	Type	Required	Description
`name`	string	Yes	Project name (1–200 characters)
`description`	string	No	Optional description of the project’s purpose

Example request:

curl -X POST https://api.pyramid-ai.com/api/v2/projects \
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marina Bay Tower - Safety Docs",
    "description": "All safety and compliance documents for the Marina Bay Tower project"
  }'

Example response 201 Created:

{
  "success": true,
  "data": {
    "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
    "name": "Marina Bay Tower - Safety Docs",
    "description": "All safety and compliance documents for the Marina Bay Tower project",
    "document_count": 0,
    "created_at": "2026-05-22T10:00:00Z",
    "updated_at": "2026-05-22T10:00:00Z"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Error responses:

Status	Code	When
`400`	`VALIDATION_ERROR`	Missing or invalid `name`
`401`	`UNAUTHORIZED`	Missing or invalid API key

GET /api/v2/projects

Returns all projects for the authenticated organization. Supports pagination.

Authentication: Bearer token required

Query parameters:

Parameter	Type	Default	Description
`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/projects?limit=10&offset=0 \
  -H "Authorization: Bearer pai_live_YOUR_KEY"

Example response 200 OK:

{
  "success": true,
  "data": [
    {
      "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
      "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
      "name": "Marina Bay Tower - Safety Docs",
      "description": "All safety and compliance documents for the Marina Bay Tower project",
      "document_count": 42,
      "created_at": "2026-05-22T10:00:00Z",
      "updated_at": "2026-05-22T14:30:00Z"
    }
  ],
  "request_id": "...",
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

GET /api/v2/projects/{id}

Returns details for a single project.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Project ID

Example request:

curl https://api.pyramid-ai.com/api/v2/projects/7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer pai_live_YOUR_KEY"

Example response 200 OK:

{
  "success": true,
  "data": {
    "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
    "name": "Marina Bay Tower - Safety Docs",
    "description": "All safety and compliance documents for the Marina Bay Tower project",
    "document_count": 42,
    "created_at": "2026-05-22T10:00:00Z",
    "updated_at": "2026-05-22T14:30:00Z"
  },
  "request_id": "..."
}

Error responses:

Status	Code	When
`401`	`UNAUTHORIZED`	Missing or invalid API key
`404`	`NOT_FOUND`	Project does not exist or belongs to a different organization

PATCH /api/v2/projects/{id}

Updates a project’s name and/or description. Only the fields you include are changed.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Project ID

Request body:

Field	Type	Required	Description
`name`	string	No	New project name (1–200 characters)
`description`	string	No	New description (max 500 characters, or null to clear)

At least one field must be provided.

Example request:

curl -X PATCH https://api.pyramid-ai.com/api/v2/projects/7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marina Bay Tower - All Documents"}'

Example response 200 OK:

{
  "success": true,
  "data": {
    "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
    "name": "Marina Bay Tower - All Documents",
    "description": "All safety and compliance documents for the Marina Bay Tower project",
    "document_count": 42,
    "created_at": "2026-05-22T10:00:00Z",
    "updated_at": "2026-05-22T15:00:00Z"
  },
  "request_id": "..."
}

DELETE /api/v2/projects/{id}

Permanently deletes a project. The project must have zero documents — delete all documents first, or the request will fail with 409.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Project ID

Example request:

curl -X DELETE https://api.pyramid-ai.com/api/v2/projects/7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer pai_live_YOUR_KEY"

Response 204 No Content — no response body.

Error responses:

Status	Code	When
`401`	`UNAUTHORIZED`	Missing or invalid API key
`404`	`NOT_FOUND`	Project does not exist
`409`	`CONFLICT`	Project still has documents. Delete them first

Response fields (all endpoints):

Field	Type	Description
`id`	uuid	Unique project identifier
`org_id`	string	Organization the project belongs to
`name`	string	Project name
`description`	string \| null	Project description
`document_count`	integer	Number of documents in the project
`created_at`	string	When the project was created (ISO 8601)
`updated_at`	string	When the project was last modified (ISO 8601)