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

string

required

A human-readable name for the project. 1–500 characters.

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
}

string

The project ID. Use this as projectId in the path of subsequent calls (e.g., to upload transcripts).

string

The project name you supplied.

number

Number of transcripts associated with the project. Zero immediately after creation.

string | null

ISO 8601 timestamp of the most recent transcript upload. null until you upload one.

string

ISO 8601 creation timestamp.

string

ISO 8601 timestamp of the most recent update.

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

number

default:"1"

Page number (1-indexed).

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