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

# API reference

> Conventions, authentication, and structure of the Metal REST API.

The Metal API is a JSON REST API for working with your firm's context layer: companies, deals, people, documents, activities, enrichments, scores, screenings, lists, workflows, and more. This reference documents every endpoint with an interactive playground. Set your credentials once and send live requests from the docs.

## Base URL

```
https://api.metal.ai
```

## Conventions

<Columns cols={2}>
  <Card title="Versioning" icon="code-branch">
    All endpoints live under the `/v1` prefix.
  </Card>

  <Card title="JSON everywhere" icon="brackets-curly">
    Requests and responses use `application/json`.
  </Card>

  <Card title="Data envelope" icon="box">
    Successful responses wrap their payload in a top-level `data` field.
  </Card>

  <Card title="Org scoping" icon="shield-halved">
    Every request is automatically scoped to your API key's organization.
  </Card>
</Columns>

## Authentication

Send both API key headers on every request:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.metal.ai/v1/companies \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"
```

See [Authentication](/authentication) for how to create and manage keys.

## Identifiers

Resource IDs are 24-character hexadecimal strings (for example, `665f1c2a9b1e4a0012a3b4c5`). Companies, deals, and people can also be addressed by your own `externalId` or `externalReference`.

## Conventions reference

| Topic            | Behavior                                                                          |
| ---------------- | --------------------------------------------------------------------------------- |
| Success envelope | `{ "data": ... }`                                                                 |
| List envelope    | `{ "data": [ ... ] }`                                                             |
| Search envelope  | `{ "data": [ ... ], "metadata": { ... } }`                                        |
| Errors           | `{ "error": "message" }`. See [Errors](/guides/errors).                           |
| Pagination       | `page`, `limit`, `lt`, `sort`, `direction`. See [Pagination](/guides/pagination). |
| Rate limits      | `429` with backoff. See [Rate limits](/guides/rate-limits).                       |

## API sections

The sidebar groups endpoints into sections by how you typically use them:

<CardGroup cols={2}>
  <Card title="Core records" icon="database">
    Companies, deals, people, documents, and activities — the primary objects in your pipeline.
  </Card>

  <Card title="Enrichment & scoring" icon="sparkles">
    Enrichments, scores, and screenings — AI-powered intelligence on your records.
  </Card>

  <Card title="Lists & taxonomy" icon="table-list">
    Lists, tags, and your industry/sector/subsector taxonomy.
  </Card>

  <Card title="Workflows & automation" icon="robot">
    Run and monitor AI workflows.
  </Card>

  <Card title="Data" icon="chart-line">
    Time-series metrics and observations via the data layer.
  </Card>

  <Card title="Administration" icon="building-user">
    API keys, teams, and workspaces for your organization.
  </Card>
</CardGroup>

## Resources

Jump to a concept for background on how these resources fit together:

<CardGroup cols={3}>
  <Card title="API keys" icon="key" href="/authentication">
    Create, list, and revoke API keys.
  </Card>

  <Card title="Companies" icon="building" href="/concepts/data-model">
    Manage and enrich companies.
  </Card>

  <Card title="Deals" icon="handshake" href="/concepts/data-model">
    Track opportunities through your pipeline.
  </Card>

  <Card title="People" icon="user" href="/concepts/data-model">
    Manage contacts and relationships.
  </Card>

  <Card title="Documents" icon="file-lines" href="/guides/search">
    Search ingested documents.
  </Card>

  <Card title="Lists" icon="table-list" href="/concepts/platform">
    Organize and enrich resources in bulk.
  </Card>

  <Card title="Workflows" icon="robot" href="/concepts/workflows">
    Run and monitor AI workflows.
  </Card>

  <Card title="Enrichment" icon="wand-magic-sparkles" href="/concepts/enrichment">
    How Metal enriches company and deal data.
  </Card>
</CardGroup>