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

# Quickstart

> Create an API key and make your first request to the Metal API.

This guide takes you from zero to your first successful API response. You'll create an API key, authenticate a request, and create your first company.

## Prerequisites

Before you begin, you need:

* A Metal account with access to your organization's workspace
* Permission to create API keys (an organization admin can grant this)
* A terminal with `curl`, or any HTTP client

## Get started

<Steps>
  <Step title="Create an API key">
    API keys are scoped to your organization. Create one in the Metal app:

    1. Go to **Settings → Organization → API & MCP Access** (you need an admin role).
    2. In the **API Keys** card, click **Create API Key**.
    3. Enter a **Name** and click **Create**.
    4. Copy the **Client ID** and **API Key** that Metal displays.

    Each key has two parts:

    * **Client ID**: sent in the `x-metal-client-id` header
    * **API Key**: sent in the `x-metal-api-key` header

    <Warning>
      The API key secret is shown only once, at creation time. Store it in a secret manager and never commit it to source control.
    </Warning>
  </Step>

  <Step title="Set your credentials">
    Export your credentials so the examples below can read them.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export METAL_CLIENT_ID="ci_your_client_id_here"
    export METAL_API_KEY="pk_your_api_key_here"
    ```
  </Step>

  <Step title="Make your first request">
    List the companies in your organization to confirm your credentials work.

    <CodeGroup>
      ```bash cURL 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"
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      import os
      import requests

      headers = {
          "x-metal-client-id": os.environ["METAL_CLIENT_ID"],
          "x-metal-api-key": os.environ["METAL_API_KEY"],
      }

      res = requests.get("https://api.metal.ai/v1/companies", headers=headers)
      res.raise_for_status()
      print(res.json()["data"])
      ```

      ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      const res = await fetch("https://api.metal.ai/v1/companies", {
        headers: {
          "x-metal-client-id": process.env.METAL_CLIENT_ID,
          "x-metal-api-key": process.env.METAL_API_KEY,
        },
      });

      const { data } = await res.json();
      console.log(data);
      ```
    </CodeGroup>

    A successful response wraps the result in a `data` field:

    ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "data": [
        {
          "id": "665f1c2a9b1e4a0012a3b4c5",
          "canonicalName": "Acme Industrials",
          "website": "https://acme.example",
          "createdAt": "2026-06-01T12:00:00Z"
        }
      ]
    }
    ```
  </Step>

  <Step title="Create a company">
    Now write some data. The only required field is `canonicalName`.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.metal.ai/v1/companies \
        -H "x-metal-client-id: $METAL_CLIENT_ID" \
        -H "x-metal-api-key: $METAL_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{ "canonicalName": "Northwind Components" }'
      ```

      ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
      res = requests.post(
          "https://api.metal.ai/v1/companies",
          headers={**headers, "Content-Type": "application/json"},
          json={"canonicalName": "Northwind Components"},
      )
      res.raise_for_status()
      print(res.json()["data"])
      ```

      ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
      const res = await fetch("https://api.metal.ai/v1/companies", {
        method: "POST",
        headers: {
          "x-metal-client-id": process.env.METAL_CLIENT_ID,
          "x-metal-api-key": process.env.METAL_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ canonicalName: "Northwind Components" }),
      });

      const { data } = await res.json();
      console.log(data);
      ```
    </CodeGroup>
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Manage keys, headers, and the scopes available to your token.
  </Card>

  <Card title="Pagination" icon="list" href="/guides/pagination">
    Page through large collections with `page`, `limit`, and `lt`.
  </Card>

  <Card title="Enrichment" icon="sparkles" href="/concepts/enrichment">
    Enrich a company with AI-sourced firmographics and financials.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Browse every endpoint with live examples.
  </Card>
</CardGroup>

<Tip>
  Stuck on a request? Email [support@metal.ai](mailto:support@metal.ai) with the method, path, and the error body you received.
</Tip>