Conventions

The rules below hold across every endpoint, so once you have learned them on one
resource they apply to all of them.

Versioning

The API is versioned in the path: /v1 on the API host (/api/v1 in the
reference, which the API host also accepts). Breaking changes ship under a new
version; v1 stays backward compatible. New optional fields and new endpoints can
appear within v1 without notice, so parse defensively and ignore unknown fields.

JSON and field casing

• Requests and responses are JSON.
• All field names are snake_case (company_name, contact_email,
  next_cursor), on input and output.
• Send Content-Type: application/json on requests with a body.
• Timestamps are ISO 8601 / RFC 3339 strings in UTC (for example
  2026-06-14T09:30:00Z).

Pagination

List endpoints are cursor-paginated and stable under concurrent inserts, so
you never skip or double-read a record while paging. Each page looks like:

{
  "data": [ /* … */ ],
  "next_cursor": "eyJpZCI6…",
  "has_more": true
}

Pass the cursor back to fetch the next page, and stop when next_cursor is null
(or has_more is false):

# first page
curl "https://api.montavire.com/v1/suppliers?limit=100" \
  -H "X-API-Key: mv_live_…"

# next page
curl "https://api.montavire.com/v1/suppliers?limit=100&cursor=eyJpZCI6…" \
  -H "X-API-Key: mv_live_…"

Common list query parameters:

Do not construct or decode cursors yourself; treat them as opaque.

Idempotency

POST and PATCH accept an Idempotency-Key header (use a UUID per logical
operation):

• Replaying with the same key and the same body returns the original
  2xx response, with no duplicate side effect.
• Reusing the key with a different body returns 409 Conflict.

This makes safe retries trivial: if a request times out, send it again with the
same key.

curl -X POST https://api.montavire.com/v1/suppliers \
  -H "X-API-Key: mv_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f9c1b2e-7a3d-4c11-9e6a-2b8f0d4a1c77" \
  -d '{ "company_name": "Acme Corp", "contact_email": "[email protected]" }'

Read more

• Errors and rate limits
• Authentication