Skip to main content

Documentation Index

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

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

A transcript is a single conversation — a sequence of user / assistant (and optionally tool / system / human_agent) turns — that you upload into a project. The Transcripts API lets you push conversations from your AI system into Bigspin programmatically, list the transcripts in a project, and fetch a single transcript with its turns and AI-generated annotations.

​
Prerequisites

  • An API key from your workspace with the projects-write permission (for POST) or projects-read permission (for GET). See Authentication.
  • A project ID (hp-{uuid} format). Create one with POST /projects if you don’t have one yet.
  • The base URL: https://app.bigspin.ai/public/api/v1

​
Endpoints

MethodPathPermissionPurpose
POST/projects/{projectId}/transcriptsprojects-writeUpload a transcript into a project
GET/projects/{projectId}/transcriptsprojects-readList transcripts in a project (paginated, filterable)
GET/transcripts/{transcriptId}projects-readGet a single transcript with turns and annotations

​
Upload a transcript — POST /projects/{projectId}/transcripts

​
Request

curl -X POST "https://app.bigspin.ai/public/api/v1/projects/hp-550e8400-e29b-41d4-a716-446655440000/transcripts" \
  -H "Authorization: Bearer sk-bigspin-api03-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support ticket #4821",
    "modelName": "gpt-4o",
    "externalId": "ticket-4821",
    "turns": [
      { "role": "user", "content": "My order never arrived." },
      { "role": "assistant", "content": "I am sorry to hear that. Let me check your order status." }
    ]
  }'

​
Path parameter

​
projectId
string
required
The ID of the project to upload into. Must match the hp-{uuid} format. The project must belong to the same workspace as your API key.

​
Request body

​
name
string
required
A human-readable name for the transcript. 1–500 characters.
​
turns
array
required
Array of conversation turns. At least 1 turn, at most 1000.Each turn has:
  • role — one of user, assistant, system, tool, human_agent
  • content — string, up to 1 MB per turn
  • toolCalls — (optional) array of { name, args } objects for assistant tool calls
  • toolResults — (optional) array of { name, result } objects for tool responses
  • metadata — (optional) arbitrary object
  • createdAt — (optional) ISO 8601 timestamp for the turn
​
modelName
string
The name of the model that produced the assistant turns. Max 100 characters.
​
language
string
Optional language code. Max 10 characters.
​
sourceSystem
string
Optional source system identifier. Max 100 characters.
​
externalId
string
Your system’s identifier for this conversation. Max 500 characters. Useful for cross-referencing.
​
externalUserId
string
Optional end-user identifier from your system. Max 500 characters.
​
metadata
object
Arbitrary metadata object stored alongside the transcript.
​
sourceTimestamp
string
ISO 8601 timestamp of when the conversation took place.
​
process
boolean
default:"true"
Whether to run Bigspin’s annotation pipeline (structural + LLM annotation + pattern detection) after upload. Set to false to upload without analysis — useful for backfills.
Total request body size is capped at approximately 5 MB. For larger datasets, split into multiple requests or use the dashboard’s file upload (which supports up to 500 MB per file).

​
Response — 201 Created

{
  "data": {
    "id": "tr_01HXYZ...",
    "name": "Support ticket #4821",
    "model_name": "gpt-4o",
    "language": null,
    "source_system": null,
    "external_id": "ticket-4821",
    "external_user_id": null,
    "metadata": {},
    "turn_count": 2,
    "user_turn_count": 1,
    "assistant_turn_count": 1,
    "total_token_count": 18,
    "source_timestamp": null,
    "created_at": "2026-05-21T14:35:08.000Z",
    "processing_status": "queued"
  },
  "processing_time_ms": 187
}
​
data.id
string
The transcript ID. Use this in subsequent calls to fetch detail.
​
data.processing_status
string
One of:
  • queued — the annotation job was submitted to the pipeline
  • skipped — process: false was set; no analysis will run
  • error — the annotation job could not be submitted (the transcript was still created successfully)

​
Error responses

StatusTypeWhen
400invalid_request_errorThe projectId path parameter is not in hp-{uuid} format, the request body is malformed, or a required field is missing.
401authentication_errorThe API key is missing or invalid.
403authorization_errorThe key does not have the projects-write permission, or the project belongs to a different workspace.
404not_found_errorThe project does not exist.
413invalid_request_errorThe request body is too large (a single turn exceeds 1 MB, or the total payload exceeds the platform body limit).

​
List transcripts in a project — GET /projects/{projectId}/transcripts

curl -X GET "https://app.bigspin.ai/public/api/v1/projects/hp-550e8400.../transcripts?page=1&limit=50" \
  -H "Authorization: Bearer sk-bigspin-api03-your-api-key"

​
Query parameters

​
page
number
default:"1"
Page number (1-indexed).
​
limit
number
default:"20"
Results per page. Max 100.
​
q
string
Full-text search across transcript content.
​
model_name
string
Filter by model name.
​
language
string
Filter by language code.
​
source_system
string
Filter by source system.
​
annotation
string
Filter by annotation, formatted as key:value.
​
date_from
string
ISO 8601 lower bound (inclusive) on source_timestamp.
​
date_to
string
ISO 8601 upper bound (inclusive) on source_timestamp.

​
Get a single transcript — GET /transcripts/{transcriptId}

curl -X GET "https://app.bigspin.ai/public/api/v1/transcripts/tr_01HXYZ..." \
  -H "Authorization: Bearer sk-bigspin-api03-your-api-key"
Returns the transcript plus all turns and annotations. Returns 404 not_found_error if the transcript ID is unknown or belongs to a different workspace.

​
Next steps