Complete REST API reference for Brokle - authentication, endpoints, and error handling

API Reference

Name: Brokle
Author: Brokle

The Brokle REST API provides programmatic access to all platform features. This reference documents authentication, endpoints, request/response formats, and error handling.

Base URL

All API requests should be made to:

https://api.brokle.com

For self-hosted deployments, replace with your server URL.

API Architecture

Brokle provides two distinct API interfaces:

SDK API

For telemetry ingestion from your applications using API keys

Dashboard API

For dashboard operations using JWT authentication

SDK API

Base Path: /v1/*

Used by SDKs for telemetry ingestion. Authenticated via API keys.

Endpoint	Method	Description
`/v1/traces`	POST	Ingest OTLP telemetry data
`/v1/evaluations`	POST	Submit evaluation scores
`/v1/prompts/{name}`	GET	Fetch prompt by name

Dashboard API

Base Path: /api/v1/*

Used by the dashboard for management operations. Authenticated via JWT tokens.

Endpoint	Method	Description
`/api/v1/auth/*`	Various	Authentication operations
`/api/v1/organizations/*`	Various	Organization management
`/api/v1/projects/*`	Various	Project management
`/api/v1/traces/*`	Various	Trace queries and management
`/api/v1/analytics/*`	Various	Metrics and reporting

Quick Start

1. Get Your API Key

API keys are created in the Brokle dashboard under Settings → API Keys.

bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Make Your First Request

curl -X POST https://api.brokle.com/v1/traces \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bk_your_api_key" \
  -d '{
    "resourceSpans": [{
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "my-app"}}
        ]
      },
      "scopeSpans": [{
        "spans": [{
          "traceId": "abc123...",
          "spanId": "def456...",
          "name": "chat_completion",
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000001000000000"
        }]
      }]
    }]
  }'

import requests

response = requests.post(
    "https://api.brokle.com/v1/traces",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "bk_your_api_key"
    },
    json={
        "resourceSpans": [{
            "resource": {
                "attributes": [
                    {"key": "service.name", "value": {"stringValue": "my-app"}}
                ]
            },
            "scopeSpans": [{
                "spans": [{
                    "traceId": "abc123...",
                    "spanId": "def456...",
                    "name": "chat_completion",
                    "startTimeUnixNano": "1700000000000000000",
                    "endTimeUnixNano": "1700000001000000000"
                }]
            }]
        }]
    }
)

print(response.json())

const response = await fetch('https://api.brokle.com/v1/traces', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'bk_your_api_key'
  },
  body: JSON.stringify({
    resourceSpans: [{
      resource: {
        attributes: [
          { key: 'service.name', value: { stringValue: 'my-app' } }
        ]
      },
      scopeSpans: [{
        spans: [{
          traceId: 'abc123...',
          spanId: 'def456...',
          name: 'chat_completion',
          startTimeUnixNano: '1700000000000000000',
          endTimeUnixNano: '1700000001000000000'
        }]
      }]
    }]
  })
});

const data = await response.json();
console.log(data);

Request Format

Headers

Header	Required	Description
`Content-Type`	Yes	Always `application/json`
`X-API-Key`	Yes*	API key for SDK endpoints
`Authorization`	Yes*	`Bearer {token}` for Dashboard endpoints

*One of X-API-Key or Authorization is required depending on endpoint.

Request Body

All request bodies should be valid JSON:

{
  "field": "value",
  "nested": {
    "object": true
  },
  "array": [1, 2, 3]
}

Response Format

Success Response

{
  "data": {
    // Response data
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Paginated Response

{
  "data": [
    // Array of items
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8,
    "hasMore": true
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Rate Limiting

API requests are rate limited to ensure fair usage:

Plan	Requests/minute	Burst
Free	60	100
Pro	600	1000
Enterprise	Custom	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700000060

When rate limited, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after 60 seconds.",
    "retryAfter": 60
  }
}

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`pageSize`	integer	20	Items per page (max 100)
`sortBy`	string	varies	Field to sort by
`sortOrder`	string	`desc`	`asc` or `desc`

Example:

GET /api/v1/traces?page=2&pageSize=50&sortBy=startTime&sortOrder=desc

Filtering

List endpoints support filtering via query parameters:

GET /api/v1/traces?projectId=proj_123&startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z

Common filter parameters:

Parameter	Type	Description
`projectId`	string	Filter by project
`startTime`	ISO 8601	Start of time range
`endTime`	ISO 8601	End of time range
`status`	string	Filter by status

OTLP Compatibility

Brokle is fully compatible with OpenTelemetry Protocol (OTLP). You can send traces using any OTLP-compatible exporter:

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://api.brokle.com/v1/traces",
    headers={"X-API-Key": "bk_your_api_key"}
)

SDK vs Direct API

We recommend using the official SDKs instead of calling the API directly. SDKs handle batching, retries, and serialization automatically.

Feature	SDK	Direct API
Automatic batching	✅	Manual
Retry logic	✅	Manual
Type safety	✅	Manual
Compression	✅	Manual
Context propagation	✅	Manual

API Sections

Authentication

API key management and JWT authentication

Traces API

Ingest and query trace data

Spans API

Query and manage individual spans

Evaluations API

Submit and query evaluation scores

Projects API

Project management operations

Error Reference

Error codes and troubleshooting

Next Steps

API Reference

The Brokle REST API provides programmatic access to all platform features. This reference documents authentication, endpoints, request/response formats, and error handling.

Base URL

All API requests should be made to:

https://api.brokle.com

For self-hosted deployments, replace with your server URL.

API Architecture

Brokle provides two distinct API interfaces:

SDK API

For telemetry ingestion from your applications using API keys

Dashboard API

For dashboard operations using JWT authentication

SDK API

Base Path: /v1/*

Used by SDKs for telemetry ingestion. Authenticated via API keys.

Endpoint	Method	Description
`/v1/traces`	POST	Ingest OTLP telemetry data
`/v1/evaluations`	POST	Submit evaluation scores
`/v1/prompts/{name}`	GET	Fetch prompt by name

Dashboard API

Base Path: /api/v1/*

Used by the dashboard for management operations. Authenticated via JWT tokens.

Endpoint	Method	Description
`/api/v1/auth/*`	Various	Authentication operations
`/api/v1/organizations/*`	Various	Organization management
`/api/v1/projects/*`	Various	Project management
`/api/v1/traces/*`	Various	Trace queries and management
`/api/v1/analytics/*`	Various	Metrics and reporting

Quick Start

1. Get Your API Key

API keys are created in the Brokle dashboard under Settings → API Keys.

bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Make Your First Request

curl -X POST https://api.brokle.com/v1/traces \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bk_your_api_key" \
  -d '{
    "resourceSpans": [{
      "resource": {
        "attributes": [
          {"key": "service.name", "value": {"stringValue": "my-app"}}
        ]
      },
      "scopeSpans": [{
        "spans": [{
          "traceId": "abc123...",
          "spanId": "def456...",
          "name": "chat_completion",
          "startTimeUnixNano": "1700000000000000000",
          "endTimeUnixNano": "1700000001000000000"
        }]
      }]
    }]
  }'

import requests

response = requests.post(
    "https://api.brokle.com/v1/traces",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "bk_your_api_key"
    },
    json={
        "resourceSpans": [{
            "resource": {
                "attributes": [
                    {"key": "service.name", "value": {"stringValue": "my-app"}}
                ]
            },
            "scopeSpans": [{
                "spans": [{
                    "traceId": "abc123...",
                    "spanId": "def456...",
                    "name": "chat_completion",
                    "startTimeUnixNano": "1700000000000000000",
                    "endTimeUnixNano": "1700000001000000000"
                }]
            }]
        }]
    }
)

print(response.json())

const response = await fetch('https://api.brokle.com/v1/traces', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'bk_your_api_key'
  },
  body: JSON.stringify({
    resourceSpans: [{
      resource: {
        attributes: [
          { key: 'service.name', value: { stringValue: 'my-app' } }
        ]
      },
      scopeSpans: [{
        spans: [{
          traceId: 'abc123...',
          spanId: 'def456...',
          name: 'chat_completion',
          startTimeUnixNano: '1700000000000000000',
          endTimeUnixNano: '1700000001000000000'
        }]
      }]
    }]
  })
});

const data = await response.json();
console.log(data);

Request Format

Headers

Header	Required	Description
`Content-Type`	Yes	Always `application/json`
`X-API-Key`	Yes*	API key for SDK endpoints
`Authorization`	Yes*	`Bearer {token}` for Dashboard endpoints

*One of X-API-Key or Authorization is required depending on endpoint.

Request Body

All request bodies should be valid JSON:

{
  "field": "value",
  "nested": {
    "object": true
  },
  "array": [1, 2, 3]
}

Response Format

Success Response

{
  "data": {
    // Response data
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Paginated Response

{
  "data": [
    // Array of items
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8,
    "hasMore": true
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Rate Limiting

API requests are rate limited to ensure fair usage:

Plan	Requests/minute	Burst
Free	60	100
Pro	600	1000
Enterprise	Custom	Custom

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700000060

When rate limited, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after 60 seconds.",
    "retryAfter": 60
  }
}

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-indexed)
`pageSize`	integer	20	Items per page (max 100)
`sortBy`	string	varies	Field to sort by
`sortOrder`	string	`desc`	`asc` or `desc`

Example:

GET /api/v1/traces?page=2&pageSize=50&sortBy=startTime&sortOrder=desc

Filtering

List endpoints support filtering via query parameters:

GET /api/v1/traces?projectId=proj_123&startTime=2024-01-01T00:00:00Z&endTime=2024-01-31T23:59:59Z

Common filter parameters:

Parameter	Type	Description
`projectId`	string	Filter by project
`startTime`	ISO 8601	Start of time range
`endTime`	ISO 8601	End of time range
`status`	string	Filter by status

OTLP Compatibility

Brokle is fully compatible with OpenTelemetry Protocol (OTLP). You can send traces using any OTLP-compatible exporter:

from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

exporter = OTLPSpanExporter(
    endpoint="https://api.brokle.com/v1/traces",
    headers={"X-API-Key": "bk_your_api_key"}
)

SDK vs Direct API

We recommend using the official SDKs instead of calling the API directly. SDKs handle batching, retries, and serialization automatically.

Feature	SDK	Direct API
Automatic batching	✅	Manual
Retry logic	✅	Manual
Type safety	✅	Manual
Compression	✅	Manual
Context propagation	✅	Manual

API Reference

SDK API

Dashboard API

Authentication

Traces API

Spans API

Evaluations API

Projects API

Error Reference

On this page

API Reference

SDK API

Dashboard API

Authentication

Traces API

Spans API

Evaluations API

Projects API

Error Reference

On this page