Transcripts API: Upload and retrieve transcripts

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

Method	Path	Permission	Purpose
`POST`	`/projects/{projectId}/transcripts`	`projects-write`	Upload a transcript into a project
`GET`	`/projects/{projectId}/transcripts`	`projects-read`	List transcripts in a project (paginated, filterable)
`GET`	`/transcripts/{transcriptId}`	`projects-read`	Get 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

Status	Type	When
`400`	`invalid_request_error`	The `projectId` path parameter is not in `hp-{uuid}` format, the request body is malformed, or a required field is missing.
`401`	`authentication_error`	The API key is missing or invalid.
`403`	`authorization_error`	The key does not have the `projects-write` permission, or the project belongs to a different workspace.
`404`	`not_found_error`	The project does not exist.
`413`	`invalid_request_error`	The 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.

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

Authentication — set up your API key.
Projects API — create the project you’ll upload into.
Upload transcripts via the dashboard — for CSV/JSONL bulk loads up to 500 MB.

Overview

Endpoints

Annotation API

Transcripts API: Upload and retrieve transcripts

Prerequisites

Endpoints

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

Request

Path parameter

Request body

Response — `201 Created`

Error responses

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

Query parameters

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

Next steps

​Prerequisites

​Endpoints

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

​Request

​Path parameter

​Request body

​Response — 201 Created

​Error responses

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

​Query parameters

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

​Next steps

Prerequisites

Endpoints

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

Request

Path parameter

Request body

Response — `201 Created`

Error responses

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

Query parameters

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

Next steps