Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bitfab.ai/llms.txt

Use this file to discover all available pages before exploring further.

All SDKs POST to the same set of endpoints under {serviceUrl}/api/sdk/. This page documents the wire protocol so you can integrate directly without using an SDK, or debug SDK behavior. Base URL defaults to https://bitfab.ai.

​
Authentication

All endpoints require the API key in the Authorization header: 
Authorization: Bearer {apiKey}
Missing, empty, or invalid keys return 401 Unauthorized.

​
Common Request Fields

The SDKs append these fields to most request bodies:
FieldTypeDescription
sdkVersionstringThe SDK package version
sourcestringOrigin tag — "typescript-sdk", "python-sdk", etc.

​
Endpoints

​
POST /api/sdk/functions/lookup

Look up a function by name. Blocking. Request: 
{ "name": "my-function-key" }
Response 200: 
{
  "id": "uuid",
  "name": "my-function-key",
  "versionId": "uuid",
  "versionNumber": 3,
  "prompt": "...",
  "providers": [ /* ProviderDefinition[] */ ]
}
Response (not found): { "id": null } — SDKs raise a typed error pointing users to /functions.

​
POST /api/sdk/functions/{functionId}/traces

Record a trace produced by a server-side function execution (e.g. client.call(...)). Fire-and-forget. Request: 
{
  "result": "...",
  "source": "typescript-sdk",
  "inputs": { "...": "..." },
  "rawCollector": { /* BAML collector snapshot, optional */ },
  "sdkVersion": "..."
}
Response: 200 OK.

​
POST /api/sdk/externalSpans

Record a single span produced by withSpan / @span / Span / bitfab_span. Fire-and-forget. Request: 
{
  "type": "sdk-function",
  "source": "typescript-sdk-function",
  "sourceTraceId": "uuid",
  "traceFunctionKey": "my-function-key",
  "rawSpan": {
    "id": "uuid",
    "trace_id": "uuid",
    "parent_id": "uuid | null",
    "started_at": "ISO8601",
    "ended_at": "ISO8601",
    "input_source_span_id": "uuid | null",
    "span_data": {
      "name": "...",
      "type": "llm|agent|function|guardrail|handoff|custom",
      "input": {/* json */},
      "output": {/* json */},
      "input_meta": {/* superjson meta */},
      "output_meta": {/* superjson meta */},
      "function_name": "...",
      "error": "...",
      "contexts": [{}],
      "prompt": "..."
    }
  },
  "testRunId": "uuid (optional, set during replay)",
  "sdkVersion": "..."
}
Response: 200 OK.

​
POST /api/sdk/externalTraces

Record the completion of a root span’s trace. Sent once per trace when the outermost span ends. Fire-and-forget. Request: 
{
  "type": "sdk-function",
  "source": "typescript-sdk-function",
  "traceFunctionKey": "my-function-key",
  "externalTrace": {
    "id": "uuid",
    "started_at": "ISO8601",
    "ended_at": "ISO8601",
    "workflow_name": "my-function-key",
    "metadata": {/* optional */},
    "contexts": [{/* optional */}]
  },
  "completed": true,
  "sessionId": "... (optional)",
  "sdkVersion": "..."
}

​
POST /api/sdk/replay/start

Begin a replay session. Blocking. Timeout: 30 s on the client side. Request: 
{
  "traceFunctionKey": "my-function-key",
  "limit": 10,
  "traceIds": ["uuid", "..."]
}
Response 200: 
{
  "testRunId": "uuid",
  "testRunUrl": "/trace-functions/my-function-key/traces?testRunId=uuid",
  "items": [
    {
      "traceId": "uuid",
      "externalSpanId": "uuid",
      "durationMs": 1750,
      "tokens": {
        "input": 80,
        "output": 20,
        "cached": 5,
        "total": 100
      },
      "model": "claude-sonnet-4-5"
    }
  ]
}
Each items[] entry carries metrics from the historical trace being replayed: durationMs is the end-to-end wall time (integer milliseconds), tokens is an object with input/output/cached/total counts, and model is the model id. Any field may be null when the underlying trace didn’t capture it.

​
POST /api/sdk/replay/complete

Signal that a replay session finished. Request: 
{ "testRunId": "uuid" }

​
GET /api/sdk/externalSpans/{spanId}

Fetch a specific external span by ID. Used by replay internals. Returns the rawSpan object.

​
Serialization

  • Inputs and outputs in span_data.input / span_data.output are serialized using superjson by the TypeScript SDK. The input_meta / output_meta fields are the superjson meta descriptors.
  • Python, Ruby, and Go SDKs use JSON-compatible fallbacks. Objects that don’t round-trip through JSON are coerced to string via the SDK’s serialize helper.

​
Error Responses

StatusMeaning
200Success
400Malformed request body
401Missing/invalid API key
403API key valid but lacks access to the referenced resource
404Function / span / trace ID not found
429Rate limit exceeded
5xxServer error
SDKs swallow all non-2xx responses on fire-and-forget endpoints and log to stderr. Blocking endpoints (lookup, replay/start) raise typed errors.