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

# Core Concepts: The Bigspin mental model explained

> 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 cols={2}>
  <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>