Skip to main content
The Metal API is a JSON REST API for working with your firm’s context layer — companies, deals, people, documents, lists, and workflows. 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.

​
Conventions reference

TopicBehavior
Success envelope{ "data": ... }
List envelope{ "data": [ ... ] }
Search envelope{ "data": [ ... ], "metadata": { ... } }
Errors{ "error": "message" } — see Errors
Paginationpage, limit, lt, sort, direction — see Pagination
Rate limits429 with backoff — see Rate limits

​
Resources

Use the sidebar to browse endpoints by resource group, or jump to a concept:

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

Run and monitor AI workflows.