> ## 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.

# Projects API: Create and list Bigspin projects

> Create, list, and retrieve Bigspin projects via the public API. Projects hold the transcripts you upload for analysis and reporting.

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](/api-reference/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

```bash theme={null}
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

<ParamField body="name" type="string" required>
  A human-readable name for the project. 1–500 characters.
</ParamField>

<ParamField body="domain" type="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.
</ParamField>

### Response — `201 Created`

```json theme={null}
{
  "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
}
```

<ResponseField name="data.id" type="string">
  The project ID. Use this as `projectId` in the path of subsequent calls (e.g., to upload transcripts).
</ResponseField>

<ResponseField name="data.name" type="string">
  The project name you supplied.
</ResponseField>

<ResponseField name="data.transcript_count" type="number">
  Number of transcripts associated with the project. Zero immediately after creation.
</ResponseField>

<ResponseField name="data.latest_transcript_at" type="string | null">
  ISO 8601 timestamp of the most recent transcript upload. `null` until you upload one.
</ResponseField>

<ResponseField name="data.created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="data.updated_at" type="string">
  ISO 8601 timestamp of the most recent update.
</ResponseField>

<ResponseField name="processing_time_ms" type="number">
  Server-side processing time for the request.
</ResponseField>

### 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`

```bash theme={null}
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

<ParamField query="page" type="number" default="1">
  Page number (1-indexed).
</ParamField>

<ParamField query="limit" type="number" default="20">
  Results per page. Max 100.
</ParamField>

### Response — `200 OK`

```json theme={null}
{
  "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}`

```bash theme={null}
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](/api-reference/transcripts) into a project with `POST /projects/{projectId}/transcripts`.
* See the dashboard guide for creating projects through the UI: [Upload transcripts](/projects/upload-transcripts).