Metal REST API conventions and structure

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 can also be addressed by externalId or externalReference, deals by externalId, and people by 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.

Streaming endpoints

POST /v1/inference runs a single LLM completion. Accepted requests respond with a server-sent event stream (text/event-stream). Frame shapes, errorCode values, and validation errors, including timeoutSeconds, are documented on that page. The completion runs under your API key’s organization. Don’t send an organization in the body.

curl -N -X POST https://api.metal.ai/v1/inference \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Summarize this company in two sentences.","timeoutSeconds":90}'

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.

Inference

Run a single LLM completion, with optional structured JSON output.

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