API reference

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

Versioning

All endpoints live under the /v1 prefix.

JSON everywhere

Requests and responses use application/json.

Data envelope

Successful responses wrap their payload in a top-level data field.

Org scoping

Every request is automatically scoped to your API key’s organization.

Authentication

Send both API key headers on every request:

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 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.
Pagination	`page`, `limit`, `lt`, `sort`, `direction`. See Pagination.
Rate limits	`429` with backoff. See Rate limits.

API sections

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

Core records

Companies, deals, people, documents, and activities — the primary objects in your pipeline.

Enrichment & scoring

Enrichments, scores, and screenings — AI-powered intelligence on your records.

Lists & taxonomy

Lists, tags, and your industry/sector/subsector taxonomy.

Workflows & automation

Run and monitor AI workflows.

Data

Time-series metrics and observations via the data layer.

Administration

API keys, teams, and workspaces for your organization.

Resources

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

API keys

Create, list, and revoke API keys.

Companies

Manage and enrich companies.

Deals

Track opportunities through your pipeline.

People

Manage contacts and relationships.

Documents

Search ingested documents.

Lists

Organize and enrich resources in bulk.

Workflows