Conventions
Base URL and format
Section titled “Base URL and format”https://api.mety.ai/api/v1- JSON in and out, camelCase field names. Send
Content-Type: application/json. Bodies over 2 MB get413 PAYLOAD_TOO_LARGE; malformed JSON gets400 VALIDATION_FAILED. - Ids are UUID v4 strings generated by Mety.
- Enums are lower-case strings (
one_off,won). - Unknown body fields are
400. Read-only fields from a GET (id,createdAt,contactCount,lastContactedAt…) are ignored on write, so a read-modify-write is safe. - Every response carries
X-Request-Id(yours if you sent one). - Health:
GET https://api.mety.ai/api/health(liveness) andGET https://api.mety.ai/api/ready(readiness,503 NOT_READYwhen not ready). Both return{ data: { status, commit } }.
Envelopes
Section titled “Envelopes”{ "data": { "id": "…", "name": "Acme" } }Page lists (organizations, contacts, deals, feedback):
{ "data": [ … ], "meta": { "page": 1, "perPage": 50, "total": 137 } }Cursor lists (activities, timelines, history, audit events):
{ "data": [ … ], "meta": { "nextCursor": "…" } }nextCursor is null on the last page; pass it back as ?cursor=. Errors are always:
{ "error": { "code": "SCREAMING_SNAKE", "message": "Human readable, safe to show", "details": { … } } }See errors for every code.
Status codes
Section titled “Status codes”200 read or updated · 201 created · 204 deleted · 400 validation · 401 no or invalid credentials ·
402 plan limit · 403 not allowed (scope) · 404 missing or another account’s · 409 conflict ·
413 body over 2 MB · 422 domain rule broken · 429 rate limited · 503 not ready.
A missing id in the URL path is 404. A missing id in the body (for example
organizations[0].organizationId) is 422 RELATED_RECORD_NOT_FOUND with details: { field, id }.
Pagination
Section titled “Pagination”| List kind | Parameters |
|---|---|
| Page | page (from 1), perPage (≤ 100, default 50). meta.total is the full count |
| Cursor | limit (≤ 100; timelines default 30), cursor |
Filtering, sorting and sparse fields
Section titled “Filtering, sorting and sparse fields”Lists take filter[<field>][<op>]=<value>, sort=field:asc|desc[:nulls_first|nulls_last], q and
fields=id,name,email. Details in lists, filters and search.
Versions and optimistic concurrency
Section titled “Versions and optimistic concurrency”Organizations, contacts, deals and custom field definitions carry version (an integer from 1, incremented on
every change). Send the version you last read:
curl -s -X PATCH https://api.mety.ai/api/v1/contacts/$CONTACT_ID \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \ -d '{"jobTitle":"CEO","version":3}'or as a header, If-Match: 3. If someone changed the record since, you get 409 VERSION_CONFLICT with the current
record in details.current: re-apply your change on it and retry. Without version, the last write wins. A
PATCH that changes nothing keeps the version and writes no audit event.
Idempotency-Key
Section titled “Idempotency-Key”Every POST, PATCH and PUT accepts Idempotency-Key (1–200 characters). Use one for every write you might
retry.
curl -s -X POST https://api.mety.ai/api/v1/organizations \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: create-acme-2026-11-15" \ -d '{"name":"Acme Inmobiliaria","domain":"acme.es"}'- The first response is stored for 24 hours per (agent, key) and replayed to later requests with the same key,
with the header
Idempotent-Replayed: true. Client errors (4xx except 429) are stored too, so a retry gets the same error: fix the request and use a new key. - Same key, different request (method, URL, account or body):
422 IDEMPOTENCY_KEY_REUSED. - Same key while the first request is still running:
409 IDEMPOTENCY_IN_PROGRESS. Wait a second and retry with the same key. - Server errors (5xx) are not stored: a retry runs again.
Over MCP the same mechanism is the idempotencyKey tool argument.
Dry run
Section titled “Dry run”Add ?dryRun=true to any write. Mety runs the whole write in a transaction, rolls it back, and returns what the
response would have been with meta: { dryRun: true }. Nothing is stored and no email is sent. Dry runs are never
stored for idempotency. Use it before every bulk change:
curl -s -X POST "https://api.mety.ai/api/v1/organizations/upsert?dryRun=true" \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \ -d '{"matchOn":"domain","items":[{"name":"Acme","domain":"acme.es"}]}'Deduplication
Section titled “Deduplication”- Upserts match by natural key: organizations
domain | taxId | id | externalRef:<system>, contactsemail | id | externalRef:<system>, dealsid | externalRef:<system>. Re-running reportsunchanged. - Activities dedupe by
externalId(unique per account). Logging it again returns the existing activity with200andmeta: { deduplicated: true }; only new links are added. - Creates of an existing
domain,(country, taxId)or contactemailanswer409 DUPLICATEwithdetails: { field, existingId }. Uniqueness counts archived records too.
Integer minor units plus an ISO 4217 code: "amountCents": 480000, "currency": "EUR". Never floats. A deal’s
currency defaults to the account’s baseCurrency. Totals are grouped per currency and never converted.
Dates and time zones
Section titled “Dates and time zones”- Timestamps are ISO 8601 UTC strings:
2026-11-15T09:30:00.000Z. You may send any offset (2026-10-02T09:14:00+02:00); Mety stores and returns UTC. - Date-only fields (
expectedCloseOn,datecustom fields):YYYY-MM-DD. - Relative times in filters (
now-48h,today,start_of_month) use the account timezone. - An activity’s
occurredAtmay not be more than 5 minutes in the future.
Rate limits
Section titled “Rate limits”Per agent: 20 requests per second and 1 200 per minute. A bulk request (an upsert or activity batch of up to 100 items) counts once. Over the limit:
HTTP/1.1 429 Too Many RequestsRetry-After: 1{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Slow down and retry later.", "details": { "retryAfterSeconds": 1 } } }Wait Retry-After seconds, then retry. Prefer batches over many single calls.
Plan limits
Section titled “Plan limits”On the Free plan, creating past a limit answers 402 PLAN_LIMIT_REACHED with details: { limit, max, plan, upgradeUrl }. Do not retry, and do not work around it (for example by deleting records). Finish the updates you
can and pass the message to a person as is. In an upsert batch it is an item error and the other items still
apply. See limits.