Skip to main content
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

1

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
The API key secret is shown only once, at creation time. Store it in a secret manager and never commit it to source control.
2

Set your credentials

Export your credentials so the examples below can read them.
export METAL_CLIENT_ID="ci_2vzbcZFlmGc32MxAjuCAR9S7VUWtbyxb+qoy4tZLrzY="
export METAL_API_KEY="pk_diEoYNHleWyOK4oS/s/p5odjVG2wkXFwZfaP5wQ1jRA="
3

Make your first request

List the companies in your organization to confirm your credentials work.
curl https://api.metal.ai/v1/companies \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"
A successful response wraps the result in a data field:
{
  "data": [
    {
      "id": "665f1c2a9b1e4a0012a3b4c5",
      "canonicalName": "Acme Industrials",
      "website": "https://acme.example",
      "createdAt": "2026-06-01T12:00:00Z"
    }
  ]
}
4

Create a company

Now write some data. The only required field is canonicalName.
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" }'

​
Next steps

Authentication

Manage keys, headers, and the scopes available to your token.

Pagination

Page through large collections with page, limit, and lt.

Enrichment

Enrich a company with AI-sourced firmographics and financials.

API reference

Browse every endpoint with live examples.
Stuck on a request? Email support@metal.ai with the method, path, and the error body you received.