Base URL and auth
All endpoints are prefixed with:
https://<your-domain>/api/v1/tenants/<tenantId>
Authenticate with an API key sent in the X-API-Key header (the Authorization header with the ApiKey scheme also works):
X-API-Key: mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Submit a job
curl -X POST \
https://<domain>/api/v1/tenants/<tenantId>/jobs/run/<pipelineId> \
-H "X-API-Key: <api-key>" \
-H "Content-Type: application/json" \
-d '{
"inputs": { "input_file": "s3://my-bucket/data.csv", "threshold": "0.8" },
"parameterOverrides": { "cpuUnits": 4, "memoryMb": 8192 }
}'
Submit a batch
Use POST /jobs/batch/{pipelineId} to submit many jobs at once — ideal for processing hundreds of files.
Poll or subscribe
Poll GET /jobs/{jobId} for status, or configure a webhook to receive push notifications instead. Fetch results with GET /jobs/{jobId}/logs and download artifacts with GET /jobs/{jobId}/artifacts/{artifactId}/download.
Webhooks
Configure webhooks under Settings → Webhooks to receive an HTTP POST on state changes:
{ "id": "...", "type": "job.completed", "createdAt": "...", "organizationId": "...", "data": { "jobId": "...", "sequence": 1, "status": "Succeeded" } }
Events: job.started, job.completed, job.failed, job.timed_out, job.cancelled, batch.completed, pipeline.published, pipeline.updated, member.added, member.removed. Each request is signed: X-Marathoon-Signature: t=<unix>,v1=<hex>, the HMAC-SHA256 of <t>.<raw body> with your signing secret (two v1 for 24 hours after a rotation: accept any match). Deduplicate on id and reorder a job's events by data.sequence.
Rate limits
Job endpoints accept 50 requests per minute per organization and job file endpoints 20, and the whole API caps each IP address at 600 requests per minute. Past a limit you get 429 Too Many Requests with a Retry-After header: wait that many seconds, then retry. To process many files, prefer one batch over hundreds of single submissions.
Error format
{ "error": "Human-readable message", "code": "Domain.ErrorCode" }
Common statuses: 401 unauthenticated, 402 insufficient credits, 403 insufficient permissions, 404 not found, 409 conflict.
Next steps
- Full API reference
- Set up your team and scope keys