API Reference
The eClips API is JSON over HTTPS. Every request is authenticated with a bearer API key; your organization and scopes are attached to the key server-side. The base URL is https://api.eclips.tech.
Authentication
Pass your API key as a bearer token: Authorization: Bearer eck_live_…. Keys are generated from your dashboard and carry their own organization and scopes — there is no separate org header. Keep keys secret; never expose them in client-side code.
curl https://api.eclips.tech/v1/run \
-H "Authorization: Bearer $ECLIPS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_type": "procurement_specialist",
"task": "Get 3 vendor quotes for 500 laptops"
}'Endpoints
Runs
/v1/runTrigger an agent run. Returns a run_id immediately; orchestration runs asynchronously.
/v1/runsList runs for your organization (query: status, limit, offset).
/v1/runs/:idFetch a run plus any linked triage item: { run, triage_item }.
/v1/runs/:id/streamServer-Sent Events — live status updates until the run reaches a terminal state.
Triage
/v1/triageList pending human-in-the-loop items (query: limit, offset).
/v1/triage/:id/approveApprove an item and continue the blocked run (body: resolution_note?).
/v1/triage/:id/rejectReject an item and stop the blocked run (body: reason?).
Webhooks
/v1/webhooksRegister a webhook (body: url, events[]). Returns the signing secret once.
/v1/webhooksList registered webhook endpoints.
/v1/webhooks/:idDelete a webhook endpoint.
/v1/webhooks/:id/deliveriesList recent delivery attempts for a webhook.
/v1/webhooks/test/:orgIdSend a test payload to your organization's configured webhook URL.
Batches
/v1/batchesCreate a batch — run an agent over many rows (body: agent_type, rows[]).
/v1/batchesList batches for your organization (query: limit, offset).
/v1/batches/:idFetch a batch with progress counts.
/v1/batches/:id/cancelCancel an in-flight batch.
Workflows
/api/workflowsList workflows for your organization.
/api/workflowsCreate a workflow (body: name, description?, steps?, edges?).
/api/workflows/:idFetch a single workflow definition.
/api/workflows/:id/runTrigger a workflow with optional input.
/api/workflows/:id/runsList runs for a workflow.
Health
/v1/healthService health check. No authentication required.
Example response
A POST /v1/run returns the queued run:
{
"run_id": "a1b2c3d4-0000-4000-8000-000000000000",
"status": "queued",
"agent_type": "procurement_specialist",
"estimated_completion": "async"
}Webhooks
Register a webhook with POST /v1/webhooks (body: url, events[]). The response includes the signing secret once. eClips POSTs a signed payload on each event — run.completed, run.failed, and run.triage_required. Each request carries an X-eClips-Signature: sha256=… header — verify the HMAC-SHA256 digest with your signing secret before trusting the body.
Errors
Errors use standard HTTP status codes and a typed error field. The official SDK maps each to a catchable error class.
| Status | Error | Meaning |
|---|---|---|
| 400 / 422 | validation_error | Request body failed validation (e.g. missing task). |
| 401 | authentication_error | Missing or invalid API key. |
| 403 | insufficient_scope | The key lacks the required scope (e.g. agents:run). |
| 404 | not_found | Run or triage item does not exist for your org. |
| 429 | rate_limited | Too many requests. Respect the Retry-After header. |