> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudsquid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Base URL, authentication, and your first API call.

<Info>
  **Base URL:** `https://api.cloudsquid.io/api`
</Info>

## Authentication

Every request must include your API key in the `X-API-Key` header. API keys are project-scoped and generated in the Cloudsquid dashboard under **Project Settings → API Keys**.

<CodeGroup>
  ```python Python theme={null}
  import requests

  headers = {"X-API-Key": "YOUR_API_KEY"}

  response = requests.get(
      "https://api.cloudsquid.io/api/projects",
      headers=headers
  )
  ```

  ```bash cURL theme={null}
  curl https://api.cloudsquid.io/api/projects \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.cloudsquid.io/api/projects", {
    headers: { "X-API-Key": "YOUR_API_KEY" }
  });
  const projects = await response.json();
  ```
</CodeGroup>

## Your first call: list projects

`GET /projects` returns all projects in your organisation. Use the `name` field as `project_name` in subsequent requests.

```json Response theme={null}
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "my-project",
    "created_at": "2024-01-15T10:30:00Z"
  }
]
```

## Integration patterns

Choose based on your use case:

<CardGroup cols={2}>
  <Card title="Synchronous" icon="bolt">
    **Endpoints:** `/extract`, `/reconcile`

    One HTTP call. Blocks until processing is complete, then returns the full result. Best for interactive integrations and files that complete in under 60 seconds.
  </Card>

  <Card title="Asynchronous (3-step)" icon="arrows-rotate">
    **Endpoints:** `/files` → `/run` → `/run/{run_id}`

    Upload, start, poll. Returns immediately — you check status separately. Best for large files, batch workloads, and decoupled pipelines.
  </Card>
</CardGroup>

## Core concepts

<CardGroup cols={3}>
  <Card title="Table Types" icon="table" href="/concepts/table-types">
    Extraction, Reconcile, and Storage tables — and when to use each.
  </Card>

  <Card title="Pipelines" icon="microchip" href="/concepts/pipelines">
    Choose between flash and pro models based on speed and accuracy requirements.
  </Card>

  <Card title="Async Run Pattern" icon="repeat" href="/concepts/async-run-pattern">
    The upload → start → poll pattern for extraction at scale.
  </Card>
</CardGroup>