Projects API: Create and list Bigspin projects

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

Method	Path	Permission	Purpose
`POST`	`/projects`	`projects-write`	Create a new project
`GET`	`/projects`	`projects-read`	List projects in the workspace
`GET`	`/projects/{projectId}`	`projects-read`	Get 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

Status	Type	When
`400`	`invalid_request_error`	The body is missing `name`, or `name` is empty or exceeds 500 characters.
`401`	`authentication_error`	The API key is missing or invalid.
`403`	`authorization_error`	The 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

Upload transcripts into a project with POST /projects/{projectId}/transcripts.
See the dashboard guide for creating projects through the UI: Upload transcripts.

Overview

Endpoints

Annotation API

Projects API: Create and list Bigspin projects

Prerequisites

Endpoints

Create a project — `POST /projects`

Request

Request body

Response — `201 Created`

Error responses

List projects — `GET /projects`

Query parameters

Response — `200 OK`

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

Next steps

​Prerequisites

​Endpoints

​Create a project — POST /projects

​Request

​Request body

​Response — 201 Created

​Error responses

​List projects — GET /projects

​Query parameters

​Response — 200 OK

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

​Next steps

Prerequisites

Endpoints

Create a project — `POST /projects`

Request

Request body

Response — `201 Created`

Error responses

List projects — `GET /projects`

Query parameters

Response — `200 OK`

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

Next steps