List projects
Retrieves all projects accessible to the authenticated user.
GET /api/projects
Response
json
[
{
"id": "proj_abc123",
"name": "My SaaS App",
"description": "Main product repository",
"visibility": "private",
"status": "active",
"aiTier": "medium",
"repoUrl": "https://github.com/org/my-saas-app",
"githubUsername": "octocat",
"repoAuthMethod": "oauth",
"hasGithubToken": true,
"deepEnrichEnabled": true,
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-20T14:00:00Z"
}
]
Create project
Creates a new project.
POST /api/projects
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Project name |
description | string | No | Project description |
visibility | string | No | "public" or "private" (default: "private") |
Example
bash
curl -X POST https://contox.dev/api/projects \
-H "Authorization: Bearer contox_sk_yourkey" \
-H "Content-Type: application/json" \
-d '{"name": "My Project", "visibility": "private"}'
Response
json
{
"id": "proj_abc123",
"name": "My Project",
"visibility": "private",
"status": "active",
"createdAt": "2025-01-15T10:30:00Z"
}
Get project
Retrieves a single project by ID.
GET /api/projects/[id]
Parameters
| Parameter | Type | Location | Description |
|---|---|---|---|
id | string | Path | The project ID |
Response
json
{
"id": "proj_abc123",
"name": "My Project",
"description": "Main product repository",
"visibility": "private",
"status": "active",
"memberCount": 3,
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-20T14:00:00Z"
}
Update project
Updates a project's properties.
PATCH /api/projects/[id]
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | New project name |
description | string | No | New description |
visibility | string | No | "public" or "private" |
status | string | No | Project status |
aiTier | string | null | No | AI model override: "small", "medium", or null (plan default) |
repoUrl | string | null | No | GitHub repository URL (must match https://github.com/owner/repo) |
githubToken | string | No | GitHub PAT (write-only, encrypted server-side, never returned in GET) |
deepEnrichEnabled | boolean | No | Enable/disable deep enrichment for this project |
disconnectGithub | literal true | No | Clears all GitHub fields (token, username, repo, auth method) |
Example
bash
curl -X PATCH https://contox.dev/api/projects/proj_abc123 \
-H "Authorization: Bearer contox_sk_yourkey" \
-H "Content-Type: application/json" \
-d '{"name": "Updated Name", "visibility": "public"}'
Delete project
Permanently deletes a project and all associated data.
DELETE /api/projects/[id]
Response
Returns 204 No Content on success.
List project members
Retrieves all members of a project.
GET /api/projects/[id]/members
Response
json
[
{
"userId": "user_abc123",
"name": "Jane Doe",
"email": "jane@example.com",
"role": "owner",
"joinedAt": "2025-01-15T10:30:00Z"
},
{
"userId": "user_def456",
"name": "John Smith",
"email": "john@example.com",
"role": "member",
"joinedAt": "2025-01-18T09:00:00Z"
}
]
Add project member
Adds a member to a project.
POST /api/projects/[id]/members
Request body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email of the user to add |
role | string | No | "admin" or "member" (default: "member") |
Remove project member
Removes a member from a project.
DELETE /api/projects/[id]/members
Request body
| Field | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | ID of the user to remove |
Get HMAC secret
Retrieves the HMAC secret for a project, used for signing V2 ingest requests.
GET /api/projects/[id]/hmac-secret
Response
json
{
"secret": "hmac_secret_abc123def456..."
}
Only project owners and admins can access this endpoint. The secret is used to sign requests to the V2 Ingest endpoint.
Next steps
- Contexts -- Manage project contexts
- Team -- Manage team members
- HMAC Signing -- How to use the HMAC secret