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 project is a container for the transcripts you upload to Bigspin. Each project is scoped to a single workspace and identified by an ID with the prefix hp- (for example, hp-550e8400-e29b-41d4-a716-446655440000). Use the Projects API to create new projects from your code, list the projects in your workspace, and fetch a single project’s executive summary once a report has been generated.

​
Prerequisites

  • An API key from your workspace with the projects-write permission (for POST) or projects-read permission (for GET). See Authentication.
  • The base URL: https://app.bigspin.ai/public/api/v1

​
Endpoints

MethodPathPermissionPurpose
POST/projectsprojects-writeCreate a new project
GET/projectsprojects-readList projects in the workspace
GET/projects/{projectId}projects-readGet a single project (with executive summary when available)

​
Create a project — POST /projects

​
Request

curl -X POST "https://app.bigspin.ai/public/api/v1/projects" \
  -H "Authorization: Bearer sk-bigspin-api03-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 support transcript review"
  }'

​
Request body

​
name
string
required
A human-readable name for the project. 1–500 characters.
​
domain
string
Optional domain pack. Locks the taxonomy used during analysis. Currently supported values are general (default) and ai_coding. Most callers can omit this field.

​
Response — 201 Created

{
  "data": {
    "id": "hp-550e8400-e29b-41d4-a716-446655440000",
    "name": "Q2 support transcript review",
    "transcript_count": 0,
    "latest_transcript_at": null,
    "created_at": "2026-05-21T14:32:11.000Z",
    "updated_at": "2026-05-21T14:32:11.000Z"
  },
  "processing_time_ms": 42
}
​
data.id
string
The project ID. Use this as projectId in the path of subsequent calls (e.g., to upload transcripts).
​
data.name
string
The project name you supplied.
​
data.transcript_count
number
Number of transcripts associated with the project. Zero immediately after creation.
​
data.latest_transcript_at
string | null
ISO 8601 timestamp of the most recent transcript upload. null until you upload one.
​
data.created_at
string
ISO 8601 creation timestamp.
​
data.updated_at
string
ISO 8601 timestamp of the most recent update.
​
processing_time_ms
number
Server-side processing time for the request.

​
Error responses

StatusTypeWhen
400invalid_request_errorThe body is missing name, or name is empty or exceeds 500 characters.
401authentication_errorThe API key is missing or invalid.
403authorization_errorThe key does not have the projects-write permission.

​
List projects — GET /projects

curl -X GET "https://app.bigspin.ai/public/api/v1/projects?page=1&limit=20" \
  -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.

​
Response — 200 OK

{
  "data": [
    {
      "id": "hp-550e8400-e29b-41d4-a716-446655440000",
      "name": "Q2 support transcript review",
      "transcript_count": 142,
      "latest_transcript_at": "2026-05-20T18:14:02.000Z",
      "created_at": "2026-05-12T09:00:00.000Z",
      "updated_at": "2026-05-20T18:14:02.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  },
  "processing_time_ms": 28
}

​
Get a single project — GET /projects/{projectId}

curl -X GET "https://app.bigspin.ai/public/api/v1/projects/hp-550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk-bigspin-api03-your-api-key"
Returns the project, plus the executive summary from the latest completed report if one exists. Returns 404 not_found_error if the project ID is unknown or belongs to a different workspace.

​
Next steps