Projects

Create and manage knowledge projects

Projects

Create and manage knowledge projects

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:

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

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:

1 {
2   "success": true,
3   "data": [
4     {
5       "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
6       "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
7       "name": "Marina Bay Tower - Safety Docs",
8       "description": "All safety and compliance documents for the Marina Bay Tower project",
9       "document_count": 42,
10       "created_at": "2026-05-22T10:00:00Z",
11       "updated_at": "2026-05-22T14:30:00Z"
12     }
13   ],
14   "request_id": "...",
15   "pagination": {
16     "limit": 10,
17     "offset": 0,
18     "total": 1
19   }
20 }

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:

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

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:

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

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)

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:

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

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:

1 {
2   "success": true,
3   "data": [
4     {
5       "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
6       "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
7       "name": "Marina Bay Tower - Safety Docs",
8       "description": "All safety and compliance documents for the Marina Bay Tower project",
9       "document_count": 42,
10       "created_at": "2026-05-22T10:00:00Z",
11       "updated_at": "2026-05-22T14:30:00Z"
12     }
13   ],
14   "request_id": "...",
15   "pagination": {
16     "limit": 10,
17     "offset": 0,
18     "total": 1
19   }
20 }

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:

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

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:

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

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)

$	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"
>	}'

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

$	curl https://api.pyramid-ai.com/api/v2/projects?limit=10&offset=0 \
>	-H "Authorization: Bearer pai_live_YOUR_KEY"

1	{
2	"success": true,
3	"data": [
4	{
5	"id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
6	"org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
7	"name": "Marina Bay Tower - Safety Docs",
8	"description": "All safety and compliance documents for the Marina Bay Tower project",
9	"document_count": 42,
10	"created_at": "2026-05-22T10:00:00Z",
11	"updated_at": "2026-05-22T14:30:00Z"
12	}
13	],
14	"request_id": "...",
15	"pagination": {
16	"limit": 10,
17	"offset": 0,
18	"total": 1
19	}
20	}

$	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"}'

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