Conventions

These conventions apply across all endpoints.

Request IDs

Every authenticated response includes an X-Request-Id header, and every error body includes a request_id. Log it and include it when contacting support. (The unauthenticated GET /api/v1/health check is the exception — it does not return X-Request-Id.)

Pagination

List endpoints accept limit (default 50, max 100) and offset (default 0) query parameters, and include has_more and total in the response. Newer list endpoints (target-audiences, signatures, conversations, conversation messages) return results under a data key. The original GET /campaigns and GET /lists endpoints return their arrays under top-level campaigns / lists keys for backward compatibility (no data key).

curl "https://app.machfive.io/api/v1/campaigns?limit=20&offset=40" \
  -H "Authorization: Bearer YOUR_API_KEY"

Idempotency

Selected write requests accept an Idempotency-Key header (any unique string, e.g. a UUID). Retrying with the same key returns the original result instead of running the work again. Reusing a key with a different body returns 409 CONFLICT.

Idempotency is supported on:

• POST /api/v1/campaigns (create campaign shell)
• POST /api/v1/campaigns/:id/target-audience
• PUT /api/v1/campaigns/:id/assets/:type/selection
• POST /api/v1/campaigns/:id/branch
• POST /api/v1/campaigns/:id/preview

The generate and generate-batch endpoints do not currently support Idempotency-Key.

curl -X POST ".../target-audience" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 5f8e...-unique" \
  -H "Content-Type: application/json" \
  -d '{ "target_audience": { "id": "ta_123", "segment_name": "Fintech CFOs" } }'

Async jobs

Long-running operations return a job and are polled to completion:

• Batch generation returns a list_id; poll GET /api/v1/lists/:id until processing_status is completed or failed.
• Other async operations return a job id; poll GET /api/v1/jobs/:id until status is completed or failed. See Jobs.

Some async operations (campaign build steps, workspace regenerate) report derived status — the job is not processed by the generic worker; its status is computed from live resource readiness when you poll.

Health

GET /api/v1/health returns API status (unauthenticated) for uptime checks.

curl -X GET "https://app.machfive.io/api/v1/health"