# Create Annotation
Source: https://docs.bigspin.ai/api-reference/annotations/create-annotation

/api-reference/openapi.json post /v1/annotations
Annotate one transcript with the named annotator (sync).



# List Annotators
Source: https://docs.bigspin.ai/api-reference/annotations/list-annotators

/api-reference/openapi.json get /v1/annotators
Public registry view: the available annotators and their versions.



# Bigspin API Authentication: API Keys and Bearer Tokens
Source: https://docs.bigspin.ai/api-reference/authentication

Learn how to generate a Bigspin API key and pass it as a Bearer token in every API request, plus how to handle authentication error responses.

Every request to the Bigspin public API must include an API key. API keys authenticate your requests and tie them to your workspace, which determines which projects and transcripts you can access. New keys use the `sk-bigspin-api03-` prefix so you can identify them at a glance.

<Note>
  Legacy keys with the `sk-prism-api03-` prefix (issued before the Bigspin rename) are still accepted — you do not need to rotate them. New keys you create today will use `sk-bigspin-api03-`.
</Note>

## Getting an API key

<Steps>
  <Step title="Open API Keys settings">
    In the Bigspin dashboard, navigate to **Settings → API Keys**.
  </Step>

  <Step title="Create a new key">
    Click **Create API Key**, give it a descriptive name (for example, `production-prompt-fetcher`), and optionally add a description. Then click **Create API Key**.
  </Step>

  <Step title="Copy the key immediately">
    Bigspin shows the full key only once. Copy it to a secure location — a secrets manager, environment variable, or vault — before closing the dialog.
  </Step>
</Steps>

<Warning>
  Bigspin cannot show you the full key again after you close the creation dialog. If you lose it, revoke the key and create a new one.
</Warning>

## Including the key in requests

Pass your API key in the `Authorization` header using the Bearer scheme:

```
Authorization: Bearer YOUR_API_KEY
```

Here is a complete example using curl:

```bash theme={null}
curl -X GET "https://app.bigspin.ai/public/api/v1/projects" \
  -H "Authorization: Bearer sk-bigspin-api03-your-api-key" \
  -H "Content-Type: application/json"
```

## Permissions

API keys can be scoped to specific permissions when you create them. The current permissions are:

| Permission       | Grants access to                                  |
| ---------------- | ------------------------------------------------- |
| `projects-read`  | List and read projects, list and read transcripts |
| `projects-write` | Create projects, upload transcripts               |

Leaving an API key with no permission restrictions grants full access. Scope keys to least privilege when integrating with production systems.

<Note>
  Legacy keys may carry a `halfpipe-transcripts-write` permission instead of `projects-write` — both are accepted for the create-project and upload-transcript endpoints, so existing integrations continue to work without changes.
</Note>

<Warning>
  **Response shape change for legacy `/halfpipe/*` routes (2026-05).** `POST /public/api/v1/halfpipe/sessions` and `POST /public/api/v1/halfpipe/transcripts` now return the same response shape as the new `/projects/*` routes: snake\_case fields (`created_at`, `model_name`, `turn_count`), no `success: true` flag, and no `workspaceId` field. If your integration parses `response.success` or `response.data.workspaceId` from these endpoints, update it to read from the new shape. The path and request body are unchanged.
</Warning>

<Note>
  JWT tokens (which start with `ey`) are not supported on most public API endpoints. Always use an API key with the `sk-bigspin-api03-` prefix.
</Note>

## Authentication error responses

When the API cannot authenticate your request, it returns a JSON error body alongside an HTTP error status.

**Missing API key — `401 Unauthorized`**

```json theme={null}
{
  "error": {
    "message": "API key required for authentication",
    "type": "authentication_error",
    "code": 401
  }
}
```

**Invalid API key — `401 Unauthorized`**

```json theme={null}
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": 401
  }
}
```

**Insufficient permissions — `403 Forbidden`**

```json theme={null}
{
  "error": {
    "message": "API key does not have permission for this endpoint",
    "type": "authorization_error",
    "code": 403
  }
}
```

A `403` response means your key is valid but does not have access to the specific project or transcript you requested. Check that the key was created in the same workspace that owns the resource, and that it carries the right permission (`projects-read` for read endpoints, `projects-write` for create/upload endpoints).

## Managing API keys

From **Settings → API Keys** you can:

* **Revoke** a key to suspend access without permanently deleting it. Revoked keys can be reactivated later.
* **Delete permanently** a key to remove it from the system entirely. This cannot be undone.
* **View last-used timestamps** to audit which keys are still active.

## Security best practices

* Store API keys in environment variables or a secrets manager. Never hard-code them in source files or commit them to version control.
* Create one key per environment (development, staging, production) so you can rotate or revoke them independently.
* Revoke any key immediately if you suspect it has been exposed.
* Rotate keys periodically as part of routine security hygiene.


# Create Batch
Source: https://docs.bigspin.ai/api-reference/batches/create-batch

/api-reference/openapi.json post /v1/batches
Spec'd in OpenAPI now; returns 501 in v1 (see RFC 000055).



# Get Batch
Source: https://docs.bigspin.ai/api-reference/batches/get-batch

/api-reference/openapi.json get /v1/batches/{batch_id}
Spec'd in OpenAPI now; returns 501 in v1 (see RFC 000055).



# Health
Source: https://docs.bigspin.ai/api-reference/health/health

/api-reference/openapi.json get /health
Liveness probe reporting which compute substrate serves traffic.



# Bigspin Public API Overview: Endpoints and Base URL
Source: https://docs.bigspin.ai/api-reference/introduction

An overview of Bigspin's public API, base URL, authentication model, and links to the Projects and Transcripts API references.

The Bigspin public API lets you push conversation data into Bigspin and read back the results of analysis. The two resources you'll work with are **Projects** (containers for the transcripts you want analyzed) and **Transcripts** (the conversations themselves, plus turn-level annotations once analysis runs).

## Base URL

All public API endpoints are served from:

```
https://app.bigspin.ai/public/api/v1
```

Every endpoint path in this reference is relative to this base URL. For example, the full URL for the create-project endpoint is:

```
https://app.bigspin.ai/public/api/v1/projects
```

## Authentication

All requests must include an API key in the `Authorization` header as a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

You can generate API keys from your Bigspin dashboard under **Settings → API Keys**. See the [Authentication](/api-reference/authentication) page for full details, including how to handle authentication errors and how to scope keys with permissions.

## Rate limiting

Rate limiting details are not currently published. If you encounter `429 Too Many Requests` responses or need to understand the limits that apply to your plan, contact Bigspin support.

## Available APIs

<CardGroup>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    How to create and use API keys to authenticate every request.
  </Card>

  <Card title="Projects" icon="folder" href="/api-reference/projects">
    Create, list, and retrieve Bigspin projects.
  </Card>

  <Card title="Transcripts" icon="message" href="/api-reference/transcripts">
    Upload conversation transcripts into a project; list and fetch transcripts with turns and annotations.
  </Card>
</CardGroup>


# Projects API: Create and list Bigspin projects
Source: https://docs.bigspin.ai/api-reference/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 type="string">
  A human-readable name for the project. 1–500 characters.
</ParamField>

<ParamField 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 type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  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).


# Transcripts API: Upload and retrieve transcripts
Source: https://docs.bigspin.ai/api-reference/transcripts

Upload conversation transcripts into a Bigspin project via the public API, list transcripts in a project, and retrieve a single transcript with turns and annotations.

A **transcript** is a single conversation — a sequence of `user` / `assistant` (and optionally `tool` / `system` / `human_agent`) turns — that you upload into a [project](/api-reference/projects). 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](/api-reference/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

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

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

### Request body

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

<ParamField type="array">
  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
</ParamField>

<ParamField type="string">
  The name of the model that produced the assistant turns. Max 100 characters.
</ParamField>

<ParamField type="string">
  Optional language code. Max 10 characters.
</ParamField>

<ParamField type="string">
  Optional source system identifier. Max 100 characters.
</ParamField>

<ParamField type="string">
  Your system's identifier for this conversation. Max 500 characters. Useful for cross-referencing.
</ParamField>

<ParamField type="string">
  Optional end-user identifier from your system. Max 500 characters.
</ParamField>

<ParamField type="object">
  Arbitrary metadata object stored alongside the transcript.
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp of when the conversation took place.
</ParamField>

<ParamField type="boolean">
  Whether to run Bigspin's annotation pipeline (structural + LLM annotation + pattern detection) after upload. Set to `false` to upload without analysis — useful for backfills.
</ParamField>

<Note>
  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).
</Note>

### Response — `201 Created`

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

<ResponseField name="data.id" type="string">
  The transcript ID. Use this in subsequent calls to fetch detail.
</ResponseField>

<ResponseField name="data.processing_status" type="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)
</ResponseField>

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

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

<ParamField type="number">Page number (1-indexed).</ParamField>
<ParamField type="number">Results per page. Max 100.</ParamField>
<ParamField type="string">Full-text search across transcript content.</ParamField>
<ParamField type="string">Filter by model name.</ParamField>
<ParamField type="string">Filter by language code.</ParamField>
<ParamField type="string">Filter by source system.</ParamField>
<ParamField type="string">Filter by annotation, formatted as `key:value`.</ParamField>
<ParamField type="string">ISO 8601 lower bound (inclusive) on `source_timestamp`.</ParamField>
<ParamField type="string">ISO 8601 upper bound (inclusive) on `source_timestamp`.</ParamField>

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

```bash theme={null}
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](/api-reference/authentication) — set up your API key.
* [Projects API](/api-reference/projects) — create the project you'll upload into.
* [Upload transcripts via the dashboard](/projects/upload-transcripts) — for CSV/JSONL bulk loads up to 500 MB.


# Core Concepts: The Bigspin mental model explained
Source: https://docs.bigspin.ai/core-concepts

Understand the key building blocks of Bigspin — projects, transcripts, reports, data sources, and API keys — before you dive into the product.

Bigspin is built around a small set of concepts that work together. Understanding them makes everything else in the product — and in these docs — much easier to follow. This page defines each concept and explains how they relate to one another.

<AccordionGroup>
  <Accordion title="Projects">
    A **project** is the top-level container in Bigspin. It groups a set of transcripts together with all the analysis that runs on them.

    You can have as many projects as you need — one per product, one per team, one per experiment.

    Every project shows you how many transcripts it contains and when they were last synced, so you always know how fresh your analysis is.
  </Accordion>

  <Accordion title="Transcripts">
    A **transcript** is a single recorded AI conversation. It contains one or more **turns** — individual messages exchanged between participants.

    Each turn has a `role` that identifies who sent the message:

    | Role          | Description                                       |
    | ------------- | ------------------------------------------------- |
    | `user`        | The end user interacting with the AI              |
    | `assistant`   | The AI's response                                 |
    | `human_agent` | A human support agent who joined the conversation |
    | `system`      | A system-level instruction or context message     |
    | `tool`        | Output from a tool or function call               |

    Transcripts are the raw material for everything Bigspin does. The more transcripts you add to a project, the more reliable and comprehensive your reports become.
  </Accordion>

  <Accordion title="Reports">
    A **report** is the AI-generated analysis Bigspin produces after processing a project's transcripts. Reports surface:

    * **Patterns** — Recurring topics and themes across your conversations.
    * **Issues** — Areas where your AI's responses fall short of expectations.
    * **Trends** — How quality and topic distribution change over time.

    Reports are designed to be read by domain experts, not just engineers. The findings are expressed in plain language so that product managers, quality leads, and subject matter experts can act on them directly.

    Bigspin runs analysis automatically whenever new transcripts are added to a project, so your reports stay current as your data grows.
  </Accordion>

  <Accordion title="Data Sources">
    A **data source** is how transcripts get into a project. Bigspin supports two approaches:

    **File uploads** — Upload CSV, TSV, JSON, JSONL, or Parquet files directly from the project creation modal or the project view. Each file can be up to 500 MB.

    **Integrations** — Connect a third-party tracing tool so transcripts sync automatically:

    * **LangSmith** — Connect your LangSmith workspace to stream traces into Bigspin without manual exports.
    * **Braintrust** — Connect your Braintrust account for continuous ingestion.

    When you configure an integration, you can also apply **transcript filters** — metadata-based criteria that limit which traces get pulled into a given project. This lets you create focused projects (for example, only traces tagged with a specific environment or model version) without exporting separate files.

    See [Integrations](/integrations/langsmith) for setup instructions.
  </Accordion>

  <Accordion title="API Keys">
    An **API key** is a credential that authenticates programmatic requests to the Bigspin API. You need an API key to:

    * Create projects and upload transcripts via the [Projects](/api-reference/projects) and [Transcripts](/api-reference/transcripts) APIs.
    * Read project and transcript data programmatically.

    You generate and manage API keys from **Settings → API Keys** in the dashboard. Treat your API keys like passwords — do not commit them to source control or share them publicly.

    <Warning>
      Bigspin does not display a key's secret value after initial creation. Copy it immediately and store it somewhere safe, such as a secrets manager or environment variable.
    </Warning>
  </Accordion>
</AccordionGroup>

## How the concepts fit together

A typical Bigspin workflow connects all of these concepts in sequence:

1. You create a **project**.
2. You add **transcripts** via file upload, a **data source** integration, or the [Transcripts API](/api-reference/transcripts).
3. Bigspin analyzes the transcripts and generates a **report**.
4. You act on the report's findings — refining prompts, updating training data, or adjusting your AI's behavior.
5. New transcripts flow in, a fresh report runs, and the cycle repeats.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="quickstart">
    Follow the step-by-step guide to create your first project and report.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the Projects and Transcripts APIs to push data into Bigspin programmatically.
  </Card>
</CardGroup>


# Braintrust Integration: Sync Traces into Bigspin
Source: https://docs.bigspin.ai/integrations/braintrust

Link your Braintrust account to Bigspin to automatically import experiment logs as transcripts. Filter by metadata to scope which traces each project ingests.

Connecting Braintrust to Bigspin lets you pull traces and experiment logs from your Braintrust workspace directly into Bigspin projects. Once the integration is active, you can create projects sourced from Braintrust, apply metadata filters to narrow which traces are ingested, and let Bigspin handle the rest automatically — no manual exports required.

## Connect your Braintrust account

<Steps>
  <Step title="Open Integrations settings">
    In the Bigspin dashboard, go to **Settings** > **Integrations**.
  </Step>

  <Step title="Select Braintrust">
    Click the **Braintrust** card to open the connection form.
  </Step>

  <Step title="Enter your API key">
    Paste your Braintrust API key into the field. Braintrust API keys follow the format:

    ```text theme={null}
    sk-...
    ```

    If you don't have a key yet, follow the [Braintrust authentication guide](https://www.braintrust.dev/docs/reference/api/auth) to generate one.
  </Step>

  <Step title="Validate and connect">
    Bigspin validates the key against your Braintrust account before saving. If validation succeeds, the integration appears as connected on the Integrations page.

    <Note>
      Validation happens automatically when you submit the form. Bigspin does not store your key until the check passes.
    </Note>
  </Step>
</Steps>

## Create a project with Braintrust as the data source

Once the integration is connected, you can create Bigspin projects that pull from your Braintrust workspace.

<Steps>
  <Step title="Go to Projects">
    Navigate to **Projects** in the Bigspin dashboard.
  </Step>

  <Step title="Open Data Sources">
    Click **Data Sources** when setting up a new project.
  </Step>

  <Step title="Select Braintrust">
    Choose **Braintrust** from the list of available sources.
  </Step>

  <Step title="Apply metadata filters (optional)">
    Bigspin fetches the metadata keys available in your Braintrust workspace and displays them in a filter panel. For each key you want to filter on:

    * Select the metadata key from the dropdown.
    * Choose or type the value to match. Bigspin shows sample values pulled from your workspace to help you pick the right one.
    * Review the **preview count** — Bigspin shows how many traces match your current filter combination before you finalize the project.

    <Tip>
      Use metadata filters to scope ingestion to a specific experiment, model version, or environment. Narrowing the filter set keeps your project focused and speeds up analysis.
    </Tip>

    You can add multiple key/value filters. Bigspin applies them together, ingesting only traces that match all conditions.
  </Step>

  <Step title="Finish creating the project">
    Complete the remaining project setup steps. Bigspin begins ingesting matching Braintrust traces automatically.
  </Step>
</Steps>

## Ongoing ingestion

After initial setup, Bigspin ingests traces from Braintrust automatically. You do not need to trigger syncs manually or re-export data from Braintrust.

<Note>
  If you rotate your Braintrust API key, return to **Settings** > **Integrations** and update the key so ingestion continues without interruption.
</Note>


# LangSmith Integration: Sync Traces into Bigspin
Source: https://docs.bigspin.ai/integrations/langsmith

Link your LangSmith account to Bigspin to automatically import traces as transcripts. Apply metadata filters to scope which traces each project ingests.

Connecting LangSmith to Bigspin lets you pull your LangSmith traces directly into Bigspin projects without any manual exporting or uploading. Once the integration is active, you can create projects that source data from your LangSmith workspace, apply metadata filters to scope which traces you want to analyze, and let Bigspin handle ingestion automatically.

## Connect your LangSmith account

<Steps>
  <Step title="Open Integrations settings">
    In the Bigspin dashboard, go to **Settings** > **Integrations**.
  </Step>

  <Step title="Select LangSmith">
    Click the **LangSmith** card to open the connection form.
  </Step>

  <Step title="Enter your API key">
    Paste your LangSmith API key into the field. LangSmith API keys follow the format:

    ```text theme={null}
    lsv2_pt_...
    ```

    If you don't have a key yet, follow the [LangSmith API key guide](https://docs.langchain.com/langsmith/api-key) to generate one.
  </Step>

  <Step title="Validate and connect">
    Bigspin validates the key against your LangSmith account before saving. If validation succeeds, the integration appears as connected on the Integrations page.

    <Note>
      Validation happens automatically when you submit the form. Bigspin does not store your key until the check passes.
    </Note>
  </Step>
</Steps>

## Create a project with LangSmith as the data source

Once the integration is connected, you can create Bigspin projects that pull from your LangSmith workspace.

<Steps>
  <Step title="Go to Projects">
    Navigate to **Projects** in the Bigspin dashboard.
  </Step>

  <Step title="Open Data Sources">
    Click **Data Sources** when setting up a new project.
  </Step>

  <Step title="Select LangSmith">
    Choose **LangSmith** from the list of available sources.
  </Step>

  <Step title="Apply metadata filters (optional)">
    Bigspin fetches the metadata keys available in your LangSmith workspace and displays them in a filter panel. For each key you want to filter on:

    * Select the metadata key from the dropdown.
    * Choose or type the value to match. Bigspin shows sample values pulled from your workspace to help you pick the right one.
    * Review the **preview count** — Bigspin shows how many traces match your current filter combination before you finalize the project.

    <Tip>
      Use metadata filters to scope ingestion to a specific model, environment, or user segment. Narrowing the filter set keeps your project focused and speeds up analysis.
    </Tip>

    You can add multiple key/value filters. Bigspin applies them together, ingesting only traces that match all conditions.
  </Step>

  <Step title="Finish creating the project">
    Complete the remaining project setup steps. Bigspin begins ingesting matching LangSmith traces automatically.
  </Step>
</Steps>

## Ongoing ingestion

After initial setup, Bigspin ingests traces from LangSmith automatically. You do not need to trigger syncs manually or re-export data from LangSmith.

<Note>
  If you rotate your LangSmith API key, return to **Settings** > **Integrations** and update the key so ingestion continues without interruption.
</Note>


# What Is Bigspin?
Source: https://docs.bigspin.ai/introduction

Bigspin helps you see how your users actually experience your AI agent.

Bigspin is an AI agent monitoring platform that helps teams building AI products see their invisible failures, understand why they're happening, and resolve them quickly.

By analyzing 100% of conversations rather than samples or flagged cases, Bigspin surfaces failure patterns, quality drops, and user pain points that standard monitoring tools miss entirely.

Early-stage teams use it to catch invisible failures before they tank retention, without standing up a dedicated QA team or building eval infra from scratch.

Enterprise teams use it to scale conversation analysis across millions of interactions, with the audit trail and governance leadership requires.

## How Bigspin works

Bigspin follows a simple loop that turns AI transcripts into actionable improvements:

<Steps>
  <Step title="Connect your transcripts">
    Import conversation data from files (CSV, JSONL, Parquet) or connect a data source like LangSmith or Braintrust to stream traces automatically. We run LLM annotations on every message, tool call, event, and trace — not keyword search and not just sampling. Consistent analysis across 100% of your transcripts.
  </Step>

  <Step title="See what's happening">
    Did your agent even answer the right question? Did the user encounter any friction? Was the AI factual and behaviorally consistent? What are users doing that you didn't expect?

    Each finding comes with evidence, severity, and recommended action. Your roadmap becomes a function of what users actually experience.
  </Step>

  <Step title="Act on what matters">
    Bigspin delivers a daily briefing built for product teams: what went wrong, why it happened, what to do about it. This is not another dashboard, it's an analyst working alongside you, investigating issues, surfacing patterns, and recommending what to ship next.

    Every recommendation is traceable to specific conversations, defensible to leadership, reviewable by your team, and auditable for compliance.
  </Step>
</Steps>

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="quickstart">
    Get up and running in minutes. Create your first project and start analyzing your AI agent now.
  </Card>

  <Card title="Core concepts" icon="book-open" href="core-concepts">
    Learn the key ideas behind Bigspin: projects, transcripts, reports, and the improvement cycle.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Integrate Bigspin into your stack with our Projects and Transcripts APIs.
  </Card>

  <Card title="Integrations" icon="plug" href="/integrations/langsmith">
    Connect LangSmith or Braintrust to stream traces directly into your projects.
  </Card>
</CardGroup>

## Key capabilities

| Capability       | What it does                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------- |
| **Projects**     | Organize transcripts and their analysis into focused workspaces with a defined domain.      |
| **Reports**      | AI-generated analysis that surfaces patterns, issues, and trends across your conversations. |
| **Integrations** | Continuous ingestion from LangSmith and Braintrust keeps your data fresh automatically.     |
| **API**          | Retrieve dynamically optimized prompts (Spins) and manage data programmatically.            |

<Note>
  Bigspin is built for domain experts and product teams, not just engineers. You do not need to write code to analyze transcripts, read reports, or act on findings.
</Note>

## Explore the docs

<CardGroup>
  <Card title="Connect your transcripts" icon="file-arrow-up" href="/projects/upload-transcripts">
    Learn more about supported formats and how to structure your data.
  </Card>

  <Card title="Connect data sources" icon="database" href="/projects/connect-data-sources">
    Set up continuous ingestion from LangSmith or Braintrust.
  </Card>

  <Card title="Read your reports" icon="chart-bar" href="/projects/analyze-reports">
    Understand the AI-generated reports and how to act on the findings.
  </Card>

  <Card title="Manage API keys" icon="key" href="/settings/api-keys">
    Generate and rotate API keys for programmatic access to Bigspin.
  </Card>
</CardGroup>


# Understand and Act on AI-Generated Project Reports
Source: https://docs.bigspin.ai/projects/analyze-reports

Bigspin generates AI-powered reports from your transcripts, surfacing quality issues, patterns, and trends. Learn how to view reports and improve your AI.

Reports are the analytical core of Bigspin. Once your project has transcripts, Bigspin generates a briefing — an AI-produced summary that analyzes your conversations in aggregate and identifies what your AI is doing well, where it struggles, and what recurring issues you should address. Reports give you a structured, evidence-backed view of your AI's behavior that would take hours to compile manually.

## What reports surface

A Bigspin report analyzes your project's full transcript set and surfaces:

<CardGroup>
  <Card title="Quality issues" icon="triangle-exclamation">
    Specific failure modes and errors in your AI's responses, with examples drawn directly from your transcripts.
  </Card>

  <Card title="Behavioral patterns" icon="chart-line">
    Recurring patterns in how your AI responds to certain types of inputs or contexts.
  </Card>

  <Card title="Trends over time" icon="arrow-trend-up">
    How your AI's behavior is changing as you make updates, so you can track whether improvements are taking hold.
  </Card>

  <Card title="Strengths" icon="circle-check">
    Areas where your AI is performing well, so you know what to protect when making changes.
  </Card>
</CardGroup>

## How to view reports

<Steps>
  <Step title="Open a project">
    From the Projects dashboard, click the project card you want to analyze.
  </Step>

  <Step title="Navigate to the reports section">
    Inside the project, navigate to the reports or briefing section. Bigspin displays the most recent completed report.
  </Step>

  <Step title="Read the briefing">
    The briefing organizes findings into sections covering issues, patterns, and highlights from across your transcripts. Each finding links back to specific conversations so you can investigate further.
  </Step>
</Steps>

## Briefing Freshness

The **Briefing Freshness** indicator appears next to the report and tells you when the current briefing was last generated — for example, "Updated just now" or "Updated 2h ago." It briefly highlights when a new report has just completed, so you know when you're looking at fresh analysis.

<Tip>
  If your briefing is stale — for example, after uploading a new batch of transcripts or making changes to your AI — use the **Refresh** button next to the freshness indicator to generate a new report against the latest data.
</Tip>

## The iterative improvement cycle

Reports are most valuable when you use them as part of a continuous feedback loop:

<Steps>
  <Step title="Analyze">
    Generate a report for your current transcript set. Read the briefing to understand where your AI is falling short and what's working.
  </Step>

  <Step title="Identify issues">
    Use the findings to pinpoint specific behavior problems — broken flows, unhelpful responses, edge cases your AI mishandles. Drill into individual transcripts to see the issues in context.
  </Step>

  <Step title="Make changes">
    Update your AI's prompts, instructions, or underlying logic based on what you found. Deploy the updated version.
  </Step>

  <Step title="Re-analyze">
    Upload new transcripts from your updated AI (or let your connected data source sync them automatically), then refresh the report. Compare the new briefing to the previous one to confirm your changes had the intended effect.
  </Step>
</Steps>

This cycle — analyze, fix, re-analyze — is how you systematically improve your AI's behavior over time. Each report gives you a clear signal of whether you're making progress.

<Note>
  Generating a new report requires at least some transcripts in the project. If your project is empty, upload transcripts or connect a data source first. See [Upload Transcripts](/projects/upload-transcripts) and [Connect Data Sources](/projects/connect-data-sources).
</Note>


# Connect LangSmith or Braintrust as a Data Source
Source: https://docs.bigspin.ai/projects/connect-data-sources

Sync traces from LangSmith or Braintrust into Bigspin automatically. Set up your API key in Settings and use metadata filters to scope ingested traces.

Data sources are integrations that continuously pull traces from external platforms directly into your Bigspin projects. Instead of manually exporting and uploading files, you connect your tracing tool once and Bigspin automatically ingests new traces as they appear. This keeps your project's transcript data fresh without any ongoing manual work.

Bigspin currently supports **LangSmith** and **Braintrust** as data sources, with more integrations on the way.

## Access Data Sources

From the Projects dashboard, click the **Data Sources** button in the top-right corner (next to **Create Project**). This opens the Data Sources panel where you can see available integrations and navigate to their setup pages.

## Set up LangSmith

LangSmith is a tracing and evaluation platform for LangChain-based applications. Connecting it lets Bigspin import your LangSmith traces as transcripts.

<Steps>
  <Step title="Go to Settings > Integrations">
    Navigate to **Settings** in the sidebar, then select **Integrations**.
  </Step>

  <Step title="Open the LangSmith integration">
    Find LangSmith in the integrations list and click to configure it.
  </Step>

  <Step title="Enter your LangSmith API key">
    Paste your LangSmith API key. LangSmith API keys follow the format:

    ```
    lsv2_pt_...
    ```

    You can find or create your API key in your [LangSmith account settings](https://docs.langchain.com/langsmith/api-key).
  </Step>

  <Step title="Save the integration">
    Save the configuration. Bigspin validates the key and activates the integration for your workspace.
  </Step>
</Steps>

## Set up Braintrust

Braintrust is an evaluation and tracing platform for AI applications. Connecting it lets Bigspin pull your Braintrust experiment logs and traces as transcripts.

<Steps>
  <Step title="Go to Settings > Integrations">
    Navigate to **Settings** in the sidebar, then select **Integrations**.
  </Step>

  <Step title="Open the Braintrust integration">
    Find Braintrust in the integrations list and click to configure it.
  </Step>

  <Step title="Enter your Braintrust API key">
    Paste your Braintrust API key. Braintrust API keys follow the format:

    ```
    sk-...
    ```

    You can find your API key in your [Braintrust account settings](https://www.braintrust.dev/docs/reference/api/auth).
  </Step>

  <Step title="Save the integration">
    Save the configuration. Bigspin validates the key and activates the integration for your workspace.
  </Step>
</Steps>

## Transcript Filters

When a data source is connected, you can filter which traces get ingested into a specific project. Filters are configured at project creation time and are based on **metadata key/value pairs** attached to your traces.

<Steps>
  <Step title="Open the Create Project dialog">
    Click **Create Project** from the Projects dashboard.
  </Step>

  <Step title="Add filter conditions">
    In the **Transcript Filters** section, click **Add Filter**. Select a metadata key from the dropdown (populated from your connected data source), then enter or select a matching value.

    Add as many conditions as you need by clicking **Add condition**. All conditions must match for a transcript to be included (AND logic).
  </Step>

  <Step title="Check the preview count">
    As you configure filters, Bigspin displays a **preview count** showing how many transcripts currently match your criteria. Use this to confirm your filters are scoped correctly before creating the project.
  </Step>

  <Step title="Create the project">
    Click **Create Project**. The filters are saved with the project and applied to all future syncs.
  </Step>
</Steps>

<Tip>
  If no metadata keys appear in the dropdown, make sure your traces include metadata fields in your LangSmith or Braintrust setup. Bigspin reads available keys directly from your connected source.
</Tip>

## Continuous sync

Once a data source is connected and a project is configured, Bigspin automatically ingests new traces as they arrive. You don't need to trigger imports manually — your project stays up to date as your AI application produces new conversations.

<Note>
  Transcript Filters set during project creation continue to apply to all incoming traces. Only traces that match the filter criteria are added to the project.
</Note>

## Available integrations

<CardGroup>
  <Card title="LangSmith" icon="database">
    Connect your LangSmith workspace to sync traces from LangChain-based applications. API key format: `lsv2_pt_...`
  </Card>

  <Card title="Braintrust" icon="database">
    Connect your Braintrust account to sync experiment logs and traces. API key format: `sk-...`
  </Card>
</CardGroup>

<Note>
  Additional integrations are in development. Check the Data Sources panel for the latest available options.
</Note>


# Projects: Organize Your AI Conversation Analysis
Source: https://docs.bigspin.ai/projects/overview

Projects group your AI conversation transcripts for analysis. Learn how to create, rename, delete, and navigate projects in the Bigspin dashboard.

A Project is a named container that groups a set of conversation transcripts together for analysis. Every project you create gets its own workspace where Bigspin ingests transcripts — either uploaded directly or synced from a connected data source — and generates reports that surface quality issues, behavioral patterns, and trends across those conversations.

## The Projects dashboard

The Projects dashboard is the first screen you see after logging in. It displays all of your projects as cards. Each card shows:

* **Project name**
* **Transcript count** — the total number of transcripts in the project
* **Last sync date** — when transcripts were most recently added or synced

Click any project card to open the project and navigate to its analysis views.

## Create a project

<Steps>
  <Step title="Open the Create Project dialog">
    From the Projects dashboard, click the **Create Project** button in the top-right corner.
  </Step>

  <Step title="Fill in the project details">
    Enter a **Name** (required), an optional **Description**, and any **Tags** you want to use for organization. Press **Enter** or click **Add** after typing each tag.
  </Step>

  <Step title="Optionally upload transcripts or add filters">
    You can upload transcript files directly during project creation, or skip this step and add transcripts later. If your workspace has a connected data source (such as LangSmith), you can also configure **Transcript Filters** to control which traces are included.
  </Step>

  <Step title="Create the project">
    Click **Create Project**. If you uploaded files, Bigspin begins processing them immediately and takes you to the import progress screen. Otherwise, you land directly in the new project's home view.
  </Step>
</Steps>

## Rename a project

<Steps>
  <Step title="Open the project menu">
    On the project card, click the **⋮** (vertical ellipsis) menu icon in the top-right corner of the card.
  </Step>

  <Step title="Select Rename">
    Click **Rename** from the dropdown menu.
  </Step>

  <Step title="Enter the new name">
    Type a new name in the dialog and click **Rename** (or press **Enter**).
  </Step>
</Steps>

## Delete a project

<Steps>
  <Step title="Open the project menu">
    On the project card, click the **⋮** menu icon.
  </Step>

  <Step title="Select Delete">
    Click **Delete** from the dropdown menu.
  </Step>

  <Step title="Confirm deletion">
    Confirm the action in the dialog.

    <Warning>
      Deleting a project cannot be undone. The transcripts themselves are not deleted — only their association with the project is removed.
    </Warning>
  </Step>
</Steps>

## Navigate inside a project

Clicking a project card opens the project detail view. From there you can:

<CardGroup>
  <Card title="View transcripts" icon="messages">
    Browse individual conversations and inspect turn-by-turn details.
  </Card>

  <Card title="Read reports" icon="chart-bar">
    Review AI-generated briefings that summarize quality issues, patterns, and trends.
  </Card>

  <Card title="Import more transcripts" icon="upload">
    Add additional transcript files to the project at any time.
  </Card>

  <Card title="Sync from data sources" icon="rotate">
    Trigger or monitor automatic syncs from connected integrations like LangSmith or Braintrust.
  </Card>
</CardGroup>


# Upload AI Conversation Transcripts to a Project
Source: https://docs.bigspin.ai/projects/upload-transcripts

Import transcripts into a Bigspin project using CSV, TSV, JSON, JSONL, or Parquet files. Learn the required schema and how to structure your data.

Uploading transcript files is the fastest way to get conversation data into a Bigspin project. You can upload files when you first create a project, or add more transcripts to an existing project at any time. Bigspin supports several common file formats and parses them automatically so you don't need to do any pre-processing before uploading.

## Supported file formats

Bigspin accepts the following formats:

| Format                           | Extension  |
| -------------------------------- | ---------- |
| Comma-separated values           | `.csv`     |
| Tab-separated values             | `.tsv`     |
| JSON array or object             | `.json`    |
| JSON Lines (one object per line) | `.jsonl`   |
| Apache Parquet                   | `.parquet` |

<Note>
  The maximum file size per upload is **500 MB**. If your dataset exceeds this limit, split it into multiple files and upload them together — Bigspin accepts multiple files in a single upload.
</Note>

## Expected schemas

Bigspin is flexible about column and field naming, but each transcript must contain an identifier and the conversation content.

<Tabs>
  <Tab title="CSV / TSV">
    Each row in the file represents one transcript. The following columns are recognized:

    **Required:**

    * `id` — a unique identifier for the transcript
    * `conversation` (or `messages`, `turns`, or `transcript`) — the conversation content

    **Optional:**

    * `name` — a human-readable label for the transcript
    * `timestamp` (or `started_at` or `created_at`) — when the conversation took place (ISO 8601 format recommended)

    ```csv theme={null}
    id,name,conversation,started_at
    t1,Support chat,"[{""role"":""user"",""content"":""Hi""}]",2026-03-23T04:59:52Z
    ```
  </Tab>

  <Tab title="JSON / JSONL">
    Each object represents one transcript. The following fields are recognized:

    **Required:**

    * `id` — a unique identifier for the transcript
    * `turns` — an array of turn objects, each with `role` and `content`

    **Optional:**

    * `name` — a human-readable label for the transcript
    * `started_at` (or `created_at`) — when the conversation took place

    **Valid roles for turns:** `user`, `assistant`, `human_agent`, `system`, `tool`

    **Example JSONL (one object per line):**

    ```jsonl theme={null}
    {"id": "t1", "turns": [{"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello"}], "started_at": "2026-03-23T04:59:52Z"}
    {"id": "t2", "turns": [{"role": "user", "content": "What can you do?"}, {"role": "assistant", "content": "I can help with many things."}], "started_at": "2026-03-23T05:12:00Z"}
    ```

    **Example JSON array:**

    ```json theme={null}
    [
      {
        "id": "t1",
        "turns": [
          {"role": "user", "content": "Hi"},
          {"role": "assistant", "content": "Hello"}
        ],
        "started_at": "2026-03-23T04:59:52Z"
      }
    ]
    ```
  </Tab>

  <Tab title="Parquet">
    Parquet files follow the same column conventions as CSV/TSV. Bigspin reads the schema from the file and maps recognized column names automatically.

    **Required columns:** `id` and one of `conversation`, `messages`, `turns`, or `transcript`

    **Optional columns:** `name`, `timestamp`, `started_at`, or `created_at`
  </Tab>
</Tabs>

## How to upload transcripts

You can upload transcripts when creating a new project or from inside an existing project.

### During project creation

<Steps>
  <Step title="Open the Create Project dialog">
    From the Projects dashboard, click **Create Project**.
  </Step>

  <Step title="Drag and drop or browse for files">
    In the **Upload transcripts** section of the dialog, drag your files onto the drop zone, or click the drop zone to open a file picker.

    You can select multiple files at once. Files that fail validation (wrong format or over 500 MB) are rejected individually — valid files in the same selection are still added.
  </Step>

  <Step title="Review your file list">
    Each added file appears below the drop zone with its name and size. Click the **×** next to a file to remove it before submitting.
  </Step>

  <Step title="Create the project">
    Click **Create Project**. Bigspin uploads and processes all selected files and takes you to the import progress screen.
  </Step>
</Steps>

### In an existing project

<Steps>
  <Step title="Open the project">
    Click the project card on the Projects dashboard to open it.
  </Step>

  <Step title="Click the import button">
    Inside the project, click the **Upload** or import button to open the file upload interface.
  </Step>

  <Step title="Select your files">
    Drag files onto the drop zone or click to browse. Bigspin begins processing as soon as the upload completes.
  </Step>
</Steps>

## What happens after upload

Once you upload files, Bigspin:

1. Validates each file's format and size
2. Parses the transcripts according to the detected schema
3. Ingests the conversations into your project
4. Makes them available for analysis and reporting

<Tip>
  If a file contains columns or fields that Bigspin doesn't recognize, it ignores the unknown fields and processes everything else. Check the import progress screen for any parsing warnings.
</Tip>

## Transcript Filters (with a connected data source)

If your workspace has a data source integration (such as LangSmith) connected, a **Transcript Filters** section appears in the Create Project dialog. Filters let you scope your project to only include transcripts whose metadata matches specific key/value criteria — for example, only traces tagged with a particular environment or user segment.

As you add filter conditions, Bigspin shows a live **preview count** of how many transcripts currently match. Filters are applied at the subscription level and continue to be enforced on new traces as they sync in.

<Note>
  Transcript Filters are only available when a data source integration is connected to your workspace. See [Connect Data Sources](/projects/connect-data-sources) for setup instructions.
</Note>


# Bigspin Quickstart: From Sign-Up to First Report
Source: https://docs.bigspin.ai/quickstart

Go from sign-up to your first AI-generated report in minutes. Create a project, upload transcripts, and read your first analysis results.

The fastest way to understand what Bigspin can do is to see it work on your own data. This guide takes you through every step — from creating an account to reading your first report. If you have a file of AI conversation transcripts ready, the whole process takes just a few minutes.

<Steps>
  <Step title="Sign up or log in">
    Go to [app.bigspin.ai](https://app.bigspin.ai) and create an account, or log in if you already have one. After signing in, you land on the **Projects** page — your central workspace for organizing transcript analysis and accessing reports.
  </Step>

  <Step title="Create a project">
    Click **Create Project** in the top-right corner. A modal appears with the following fields:

    * **Name** — A short, descriptive label for this project (required).
    * **Description** — Optional context about what this project covers.
    * **Tags** — Optional labels to help you organize and filter projects. Type a tag and press **Add** (or hit Enter) to attach it.

    After filling in the details, you can upload transcript files directly in the modal (see the next step), or click **Create Project** to create an empty project and add files later.
  </Step>

  <Step title="Upload your transcripts ">
    Drag and drop your transcript files onto the upload zone, or click it to browse. You can add multiple files at once. Or, you can connect via a data source like LangSmith or Braintrust (scroll down for those instructions).

    **Supported formats:** CSV, TSV, JSON, JSONL, Parquet — up to 500 MB per file.

    #### JSONL format (recommended)

    Each line in a JSONL file must be a valid JSON object. Include an `id`, a `turns` array, and an optional `started_at` timestamp:

    ```jsonl theme={null}
    {"id": "t1", "turns": [{"role": "user", "content": "Hi"}, {"role": "assistant", "content": "Hello"}], "started_at": "2026-03-23T04:59:52Z"}
    ```

    Valid roles for turns: `user`, `assistant`, `human_agent`, `system`, `tool`.

    #### CSV / TSV format

    Your file needs these columns (the parser accepts flexible naming):

    | Column               | Required | Accepted names                                    |
    | -------------------- | -------- | ------------------------------------------------- |
    | Conversation ID      | Yes      | `id`                                              |
    | Conversation content | Yes      | `conversation`, `messages`, `turns`, `transcript` |
    | Conversation name    | No       | `name`                                            |
    | Timestamp            | No       | `timestamp`, `started_at`, `created_at`           |

    <Tip>
      JSONL is the most reliable format because the turn structure is explicit. Use it when you have control over the export format.
    </Tip>

    #### Connecting a data source instead

    If your traces live in LangSmith or Braintrust, click **Data Sources** on the Projects page to configure an integration. Once connected, transcripts sync automatically — no file uploads needed. See the [Integrations](/integrations/langsmith) section for setup details.
  </Step>

  <Step title="Wait for analysis">
    After you upload files, Bigspin processes your transcripts automatically. You can track progress directly in the project view. Processing time depends on the number of transcripts — most uploads complete within a few minutes.

    <Note>
      You do not need to keep the browser open during processing. Bigspin runs the analysis in the background.
    </Note>
  </Step>

  <Step title="View your first report">
    Once processing finishes, open your project and navigate to its report. The report surfaces:

    * **Patterns** — Recurring themes and topics across your conversations.
    * **Issues** — Problem areas where your AI's responses fall short.
    * **Trends** — How quality and topic distribution shift over time.

    Use these findings to inform your next prompt update, training data change, or product decision. After you make changes, upload a new set of transcripts and re-analyze to measure whether quality improved.
  </Step>
</Steps>

## What's next

<CardGroup>
  <Card title="Core concepts" icon="book-open" href="core-concepts">
    Learn the key ideas behind Bigspin: projects, transcripts, reports, and the improvement cycle.
  </Card>

  <Card title="Connect a data source" icon="database" href="/projects/connect-data-sources">
    Set up LangSmith or Braintrust for continuous, automatic transcript ingestion.
  </Card>

  <Card title="Connect your transcripts" icon="file-arrow-up" href="/projects/upload-transcripts">
    Learn more about supported formats and how to structure your data.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Integrate Bigspin into your stack with our Projects and Transcripts APIs.
  </Card>
</CardGroup>


# API Keys: Secure Bigspin Programmatic Access
Source: https://docs.bigspin.ai/settings/api-keys

Generate, revoke, and rotate API keys to authenticate requests to the Bigspin public API (Projects and Transcripts). Includes security best practices.

API keys are the credentials your code uses to make authenticated requests to Bigspin's public API — including the [Projects](/api-reference/projects) and [Transcripts](/api-reference/transcripts) endpoints. Each key is scoped to your organization's workspace, so any API calls made with a key operate within your organization's data and configuration. Bigspin displays the full key only once — at creation time — so treat generation as a deliberate step and have a secure place ready to store the value before you begin.

## Navigate to API Keys

In the dashboard sidebar, scroll to the organization section and click **API Keys** (identified by the key icon). The page lists all keys created for your workspace along with their name, a masked prefix, status, creation date, creator, and the last time each key was used.

## Create an API Key

<Steps>
  <Step title="Open the creation dialog">
    Click **Create API Key** in the top-right corner of the API Keys page.
  </Step>

  <Step title="Name your key">
    Enter a descriptive name (minimum 3 characters). A good name identifies both the integration and environment, for example `production-transcript-upload` or `staging-projects-read`.
  </Step>

  <Step title="Add an optional description">
    Use the description field to note what this key is used for, which service consumes it, or who owns it. This makes future audits much easier.
  </Step>

  <Step title="Copy the key immediately">
    After clicking **Create API Key**, Bigspin displays the full key value once. Copy it now — you will not be able to retrieve it again. Click **Done** when you have saved the key securely.
  </Step>
</Steps>

<Warning>
  Bigspin shows your API key only once, immediately after creation. If you close the dialog without copying the key, you must delete it and generate a new one. Never share your API key in chat, email, or version control.
</Warning>

## Use an API Key

Pass your key as a Bearer token in the `Authorization` header of every API request:

```bash theme={null}
curl https://app.bigspin.ai/public/api/v1/your-endpoint \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

## Security Best Practices

<CardGroup>
  <Card title="Use environment variables" icon="shield">
    Store your API key in an environment variable (for example, `BIGSPIN_API_KEY`) and reference it in code. Never hard-code a key directly in source files.
  </Card>

  <Card title="One key per integration" icon="key">
    Create a separate, named key for each application or environment. This lets you revoke a single compromised key without affecting other integrations.
  </Card>

  <Card title="Rotate compromised keys immediately" icon="refresh">
    If a key is exposed, revoke or delete it right away and generate a replacement. Update all services using the old key before they encounter an auth failure.
  </Card>

  <Card title="Audit usage regularly" icon="chart-bar">
    Check the **Last Used** column on the API Keys page to spot keys that are no longer active. Delete unused keys to reduce your attack surface.
  </Card>
</CardGroup>

<Tip>
  Add API keys to your `.gitignore` and secret-scanning rules. Many teams also use a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or Doppler) to inject keys at runtime rather than storing them in environment files that could be checked in accidentally.
</Tip>

## Manage Existing Keys

Each key in the table has an actions menu (the three-dot icon on the right) with the following options:

| Action                 | What it does                                                                                                                           |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Revoke**             | Disables the key immediately. Any requests using this key will fail. Revocation can be undone — use **Reactivate** from the same menu. |
| **Reactivate**         | Re-enables a previously revoked key.                                                                                                   |
| **Delete Permanently** | Removes the key from the system entirely. This cannot be undone.                                                                       |

## If a Key Is Compromised

<Steps>
  <Step title="Revoke or delete the key">
    Open the actions menu next to the exposed key and choose **Revoke** (reversible) or **Delete Permanently** (irreversible). This immediately blocks all requests using that credential.
  </Step>

  <Step title="Generate a replacement">
    Create a new key following the steps above. Give it a clear name that distinguishes it from the compromised key.
  </Step>

  <Step title="Update your services">
    Replace the old key value in every environment variable, secrets manager, or configuration file that referenced it. Redeploy or restart the affected services.
  </Step>

  <Step title="Review audit logs">
    Check the **Last Used** timestamp on your remaining keys and review any unusual activity in your projects to confirm no further unauthorized access occurred.
  </Step>
</Steps>


# Bigspin Billing: Manage Plans and Subscriptions
Source: https://docs.bigspin.ai/settings/billing

View your current Bigspin plan, manage your subscription, and get help with billing questions from the Billing page in your dashboard.

The Billing page gives you a clear view of your organization's current plan and subscription status. Bigspin offers tiered plans designed to scale with your team — from getting started for free to unlocking higher limits and priority support as your usage grows. You manage billing at the organization level, so any plan changes apply to all members of your organization.

## Navigate to Billing

In the dashboard sidebar, click **Billing** under the organization section. The page shows your current plan name and pricing at a glance.

## Current Plan

Your active plan is displayed prominently on the Billing page. Bigspin currently offers the following tiers:

<CardGroup>
  <Card title="Free" icon="circle">
    Get started at no cost. Includes a small number of team members, projects, and usage to explore the platform.
  </Card>

  <Card title="Premium" icon="star">
    Designed for growing teams. Increases limits on team members, projects, storage, and data transfer.
  </Card>

  <Card title="Enterprise" icon="building">
    Built for large organizations. Offers the highest limits across all dimensions and email support.
  </Card>
</CardGroup>

<Note>
  Specific feature limits and pricing are shown directly on the Billing page in your dashboard and may be updated from time to time. The page always reflects the current, accurate details for your organization.
</Note>

## Upgrade or Change Your Plan

To upgrade your subscription, visit the Billing page and follow the prompts to select a new plan. Changes take effect immediately, and your organization's limits are updated right away.

<Tip>
  If you are evaluating whether to upgrade, check the Members and usage data across your projects first. The Billing page shows which plan tier aligns with your team size and workload.
</Tip>

## Billing Help and Support

If you have questions about your invoice, need to update payment information, or encounter any billing issue, contact the Bigspin team directly:

**Email:** [support@bigspin.ai](mailto:support@bigspin.ai)

<Note>
  Include your organization name in your message so the support team can locate your account quickly.
</Note>


# Teams & Organizations: Manage Members and Access
Source: https://docs.bigspin.ai/settings/teams

Understand Bigspin's organization model, invite team members, manage roles, and switch between multiple organizations from the dashboard.

Bigspin is built around a multi-tenant organization model. Every project and transcript belongs to an organization — not to individual user accounts. This means your team's work is centralized and accessible to everyone in the organization, and switching jobs or roles doesn't fragment your data across personal accounts. You can belong to multiple organizations simultaneously, which is useful for consultants, agencies, or anyone who collaborates across separate teams or clients.

## Your Organization Profile

To manage your organization's settings, click **Settings** (the gear icon) in the organization section of the dashboard sidebar. This opens the Organization Profile, where you can update your organization's name, logo, and other details.

<Note>
  All projects and transcripts are scoped to your organization, not to individual user accounts. If a team member leaves, their work remains accessible to the rest of the organization.
</Note>

## Invite Team Members

<Steps>
  <Step title="Open the Members page">
    In the dashboard sidebar, click **Members** under the organization section. You can also navigate there directly from the Organization Profile.
  </Step>

  <Step title="Send an invitation">
    Enter the email address of the person you want to invite and click **Invite**. Bigspin will send them an email with a link to join your organization.
  </Step>

  <Step title="They accept the invitation">
    Once they click the link and sign in (or create a Bigspin account), they are added to your organization and can access its projects and components.
  </Step>
</Steps>

<Tip>
  Invited members see the same projects and data as other organization members. If you work with contractors or external collaborators who should have limited access, consider creating a separate organization for that engagement.
</Tip>

## Roles and Collaboration

Members of an organization can collaborate on all projects within it. Role-based access lets you control what different members can do:

<CardGroup>
  <Card title="Owner" icon="crown">
    The organization creator is the Owner by default. Owners can do everything Admins can, plus grant Admin or Owner access to other members and transfer ownership. Every organization has exactly one Owner at a time.
  </Card>

  <Card title="Admin" icon="user-shield">
    Admins can manage organization settings, invite and remove members, and access all projects. Admins cannot grant Admin or Owner access — only the Owner can do that.
  </Card>

  <Card title="Member" icon="users">
    Members can view and work within all projects in the organization. They cannot change organization settings or manage other members.
  </Card>
</CardGroup>

### Transfer ownership

If you need to hand off an organization — for example, when leaving the team — the current Owner can transfer ownership to another member. Transferring ownership promotes the new Owner and automatically demotes the previous Owner to Admin so they retain management access. Contact Bigspin support if you need to transfer ownership and the current Owner is unavailable.

## Switch Between Organizations

The **organization switcher** sits at the top of the sidebar, just below the Bigspin logo. Click it to see all organizations you belong to and select a different one. Switching organizations updates the entire dashboard to show that organization's projects, components, and data.

<Note>
  When you switch organizations, Bigspin refreshes your workspace data automatically. Any filters or in-progress views from the previous organization are cleared.
</Note>

## Create a New Organization

<Steps>
  <Step title="Open the organization switcher">
    Click the organization name at the top of the sidebar to open the switcher dropdown.
  </Step>

  <Step title="Create a new organization">
    Select **Create organization** from the dropdown. Enter a name and, optionally, a logo or slug for your new organization.
  </Step>

  <Step title="Start building">
    After creation, Bigspin switches you into the new organization automatically. You can immediately create projects or invite team members.
  </Step>
</Steps>

## Organization Data Ownership

Because projects and transcripts belong to the organization rather than individual users, keep the following in mind:

* **Leaving an organization** does not delete your contributions — they remain in the organization for other members.
* **Deleting an organization** removes all associated projects, transcripts, and data permanently. This action cannot be undone.
* **Personal accounts** cannot own projects. You must always be working within an organization context.

<Warning>
  Before leaving an organization, make sure another member can keep it running: if you are the Owner, transfer ownership first; if you are the sole Admin, promote another member. Otherwise, no one will be able to manage settings or invite new members.
</Warning>