Quickstart

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
The Admin role, or an Admin in your organization who can create a key for you
A terminal with curl, or any HTTP client

Get started

Create an API key

API keys are scoped to your organization. Create one in the Metal app:

Go to Settings → Organization → API & MCP Access (you need an admin role).
In the API Keys card, click Create API Key.
Enter a Name and click Create.
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.

Set your credentials

Export your credentials so the examples below can read them.

export METAL_CLIENT_ID="ci_your_client_id_here"
export METAL_API_KEY="pk_your_api_key_here"

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"

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"])

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);

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"
    }
  ]
}

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" }'

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"])

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);

Next steps

Authentication

Create API keys and send the Client ID and secret headers.

API or MCP

Choose service-level API keys or per-user MCP OAuth.

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.

Get started

Core concepts

MCP server

Prerequisites

Get started

Next steps

Authentication

API or MCP

Pagination

Enrichment

API reference

​Prerequisites

​Get started

​Next steps

Authentication

API or MCP

Pagination

Enrichment

API reference

Prerequisites

Get started

Next steps