API ReferenceEndpoints
Projects API
REST API endpoints for managing projects and settings in Brokle
Projects API
The Projects API provides endpoints for managing projects, API keys, and project settings.
Endpoints Overview
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/projects | List projects | JWT |
| POST | /api/v1/projects | Create project | JWT |
| GET | /api/v1/projects/{projectId} | Get project details | JWT |
| PATCH | /api/v1/projects/{projectId} | Update project | JWT |
| DELETE | /api/v1/projects/{projectId} | Delete project | JWT |
| GET | /api/v1/projects/{projectId}/api-keys | List API keys | JWT |
| POST | /api/v1/projects/{projectId}/api-keys | Create API key | JWT |
| DELETE | /api/v1/projects/{projectId}/api-keys/{keyId} | Revoke API key | JWT |
List Projects
GET /api/v1/projectsRetrieve all projects for the authenticated user.
Authentication
- Header:
Authorization: Bearer {jwt_token}
Query Parameters
| Parameter | Type | Description |
|---|---|---|
organizationId | string | Filter by organization |
search | string | Search by name |
page | integer | Page number |
pageSize | integer | Items per page |
Response
{
"data": [
{
"id": "proj_abc123",
"name": "Production App",
"description": "Main production application",
"organizationId": "org_xyz789",
"settings": {
"defaultModel": "gpt-4",
"retentionDays": 90
},
"stats": {
"traceCount": 15000,
"spanCount": 45000,
"totalTokens": 5000000,
"totalCost": 125.50
},
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"totalItems": 5,
"totalPages": 1
}
}Example
curl -X GET "https://api.brokle.com/api/v1/projects" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."import requests
response = requests.get(
"https://api.brokle.com/api/v1/projects",
headers={
"Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
}
)
projects = response.json()["data"]
for project in projects:
print(f"{project['name']}: {project['stats']['traceCount']} traces")Create Project
POST /api/v1/projectsCreate a new project.
Request Body
{
"name": "New Project",
"description": "Description of the project",
"organizationId": "org_xyz789",
"settings": {
"defaultModel": "gpt-4",
"retentionDays": 90,
"samplingRate": 1.0,
"privacySettings": {
"maskPII": true,
"maskPatterns": ["email", "phone", "ssn"]
}
}
}Response
{
"data": {
"id": "proj_new123",
"name": "New Project",
"description": "Description of the project",
"organizationId": "org_xyz789",
"settings": {
"defaultModel": "gpt-4",
"retentionDays": 90
},
"createdAt": "2024-01-15T10:30:00Z"
}
}Get Project
GET /api/v1/projects/{projectId}Retrieve details of a specific project.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
projectId | string | The project ID |
Response
{
"data": {
"id": "proj_abc123",
"name": "Production App",
"description": "Main production application",
"organizationId": "org_xyz789",
"settings": {
"defaultModel": "gpt-4",
"retentionDays": 90,
"samplingRate": 1.0,
"privacySettings": {
"maskPII": true,
"maskPatterns": ["email", "phone"]
},
"alertSettings": {
"errorRateThreshold": 0.05,
"latencyThreshold": 5000,
"notificationChannels": ["email", "slack"]
}
},
"stats": {
"traceCount": 15000,
"spanCount": 45000,
"totalTokens": 5000000,
"totalCost": 125.50,
"avgLatency": 1200,
"errorRate": 0.02,
"last24h": {
"traceCount": 500,
"tokenCount": 150000,
"cost": 4.50
}
},
"members": [
{
"userId": "user_123",
"email": "user@example.com",
"role": "admin"
}
],
"apiKeyCount": 3,
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
}Update Project
PATCH /api/v1/projects/{projectId}Update project settings.
Request Body
{
"name": "Updated Project Name",
"description": "Updated description",
"settings": {
"retentionDays": 180,
"samplingRate": 0.5
}
}Response
{
"data": {
"id": "proj_abc123",
"name": "Updated Project Name",
"description": "Updated description",
"settings": {
"retentionDays": 180,
"samplingRate": 0.5
},
"updatedAt": "2024-01-15T11:00:00Z"
}
}Delete Project
DELETE /api/v1/projects/{projectId}Delete a project and all associated data.
This action is permanent and cannot be undone. All traces, spans, evaluations, and API keys will be deleted.
Response
Success (204 No Content)
No response body.
API Keys
List API Keys
GET /api/v1/projects/{projectId}/api-keysList all API keys for a project.
Response
{
"data": [
{
"id": "key_abc123",
"name": "Production Key",
"prefix": "bk_abc1",
"scopes": ["traces:write", "evaluations:write"],
"lastUsed": "2024-01-15T10:25:00Z",
"createdAt": "2024-01-01T00:00:00Z",
"expiresAt": null
},
{
"id": "key_def456",
"name": "Development Key",
"prefix": "bk_def4",
"scopes": ["*"],
"lastUsed": "2024-01-14T15:00:00Z",
"createdAt": "2024-01-10T00:00:00Z",
"expiresAt": "2024-06-01T00:00:00Z"
}
]
}API key secrets are only shown once at creation time. Only the prefix is stored for identification.
Create API Key
POST /api/v1/projects/{projectId}/api-keysCreate a new API key.
Request Body
{
"name": "New Production Key",
"scopes": ["traces:write", "evaluations:write"],
"expiresAt": "2025-01-01T00:00:00Z"
}Response
{
"data": {
"id": "key_new789",
"name": "New Production Key",
"key": "bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"prefix": "bk_xxxx",
"scopes": ["traces:write", "evaluations:write"],
"expiresAt": "2025-01-01T00:00:00Z",
"createdAt": "2024-01-15T11:00:00Z"
}
}Copy the API key immediately. It will not be shown again.
Available Scopes
| Scope | Description |
|---|---|
* | Full access to all endpoints |
traces:write | Ingest trace data |
traces:read | Query trace data |
evaluations:write | Submit evaluations |
evaluations:read | Query evaluations |
prompts:read | Fetch prompts |
prompts:write | Manage prompts |
Revoke API Key
DELETE /api/v1/projects/{projectId}/api-keys/{keyId}Revoke an API key immediately.
Response
Success (204 No Content)
Project Settings
Privacy Settings
Configure data privacy controls:
{
"settings": {
"privacySettings": {
"maskPII": true,
"maskPatterns": ["email", "phone", "ssn", "credit_card"],
"customPatterns": [
{
"name": "internal_id",
"regex": "INT-\\d{8}",
"replacement": "[INTERNAL_ID]"
}
],
"excludeFields": ["password", "secret", "token"],
"retainRaw": false
}
}
}Retention Settings
Configure data retention:
{
"settings": {
"retentionDays": 90,
"archiveEnabled": true,
"archiveAfterDays": 30,
"archiveStorage": "s3"
}
}Alert Settings
Configure monitoring alerts:
{
"settings": {
"alertSettings": {
"enabled": true,
"rules": [
{
"name": "High Error Rate",
"metric": "error_rate",
"operator": "gt",
"threshold": 0.05,
"window": "5m",
"severity": "critical"
},
{
"name": "Slow Responses",
"metric": "p95_latency",
"operator": "gt",
"threshold": 5000,
"window": "10m",
"severity": "warning"
}
],
"notificationChannels": [
{
"type": "email",
"recipients": ["alerts@company.com"]
},
{
"type": "slack",
"webhookUrl": "https://hooks.slack.com/..."
}
]
}
}
}Cost Settings
Configure cost tracking:
{
"settings": {
"costSettings": {
"budget": {
"monthly": 1000,
"alertThreshold": 0.8
},
"customPricing": {
"gpt-4": {
"promptTokens": 0.03,
"completionTokens": 0.06
}
}
}
}
}Project Analytics
Get Project Stats
GET /api/v1/projects/{projectId}/statsRetrieve detailed project statistics.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
startTime | ISO 8601 | Start of time range |
endTime | ISO 8601 | End of time range |
granularity | string | hour, day, week, month |
Response
{
"data": {
"summary": {
"traceCount": 15000,
"spanCount": 45000,
"totalTokens": 5000000,
"promptTokens": 3500000,
"completionTokens": 1500000,
"totalCost": 125.50,
"avgLatency": 1200,
"p50Latency": 950,
"p95Latency": 2500,
"p99Latency": 4200,
"errorRate": 0.02,
"successRate": 0.98
},
"byModel": [
{
"model": "gpt-4",
"traceCount": 5000,
"tokens": 2000000,
"cost": 75.00
},
{
"model": "gpt-3.5-turbo",
"traceCount": 10000,
"tokens": 3000000,
"cost": 50.50
}
],
"timeSeries": [
{
"timestamp": "2024-01-15T00:00:00Z",
"traceCount": 500,
"tokens": 150000,
"cost": 4.50,
"latency": 1100
}
]
}
}Project Members
List Members
GET /api/v1/projects/{projectId}/membersList project members and their roles.
Response
{
"data": [
{
"userId": "user_123",
"email": "admin@example.com",
"name": "Admin User",
"role": "admin",
"joinedAt": "2024-01-01T00:00:00Z"
},
{
"userId": "user_456",
"email": "developer@example.com",
"name": "Developer",
"role": "member",
"joinedAt": "2024-01-10T00:00:00Z"
}
]
}Add Member
POST /api/v1/projects/{projectId}/membersRequest Body
{
"email": "newuser@example.com",
"role": "member"
}Roles
| Role | Permissions |
|---|---|
admin | Full access, manage members and settings |
member | View and create data, no settings access |
viewer | Read-only access |