Developer HubREST API · v1

API Reference

The eClips Workforce API is JSON over HTTPS. Every request carries a bearer API key, and the key decides which organization and scopes apply. The base URL is https://api.eclips.tech. The API is included on the Growth and Enterprise plans.

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, so there is no separate org header. Keep keys on the server and out of client-side code.

bash

curl https://api.eclips.tech/v1/run \
  -H "Authorization: Bearer $ECLIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "rfq_generator",
    "task": "Draft an RFQ for 500 laptops, delivery to Amman within 30 days"
  }'

Endpoints

Runs

POST

/v1/run

Start an agent run. Returns a run_id straight away; the run itself happens in the background.

GET

/v1/runs

List runs for your organization (query: status, limit, offset).

GET

/v1/runs/:id

Fetch a run plus any linked triage item: { run, triage_item }.

GET

/v1/runs/:id/stream

Server-Sent Events with live status updates until the run finishes.

Triage

GET

/v1/triage

List items waiting for a person (query: limit, offset).

POST

/v1/triage/:id/approve

Approve an item and continue the blocked run (body: resolution_note?).

POST

/v1/triage/:id/reject

Reject an item and stop the blocked run (body: reason?).

Webhooks

POST

/v1/webhooks

GET

/v1/webhooks

List registered webhook endpoints.

DELETE

/v1/webhooks/:id

Delete a webhook endpoint.

GET

/v1/webhooks/:id/deliveries

List recent delivery attempts for a webhook.

POST

/v1/webhooks/test/:orgId

Send a test payload to your organization's configured webhook URL.

Batches

POST

/v1/batches

Create a batch: one agent over up to 500 rows (body: agent_type, rows[]).

GET

/v1/batches

List batches for your organization (query: limit, offset).

GET

/v1/batches/:id

Fetch a batch with completed, failed and total row counts.

POST

/v1/batches/:id/cancel

Cancel an in-flight batch.

Health

GET

/v1/health

Service health check. No authentication required.

Example response

A POST /v1/run returns the queued run:

json

{
  "run_id": "a1b2c3d4-0000-4000-8000-000000000000",
  "status": "queued",
  "agent_type": "rfq_generator",
  "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 of these events: 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 you trust the body.

Errors

Errors use standard HTTP status codes and a typed error field. The SDK maps each one to its own error class.

Status	Error	Meaning
400 / 422	validation_error	The request body failed validation, for example a missing task or an unknown agent_type.
401	authentication_error	Missing or invalid API key.
403	insufficient_scope	The key lacks the required scope (for example agents:run), or the plan does not include the API.
404	not_found	Run or triage item does not exist for your org.
429	rate_limited	Too many requests. Respect the Retry-After header.

Use the TypeScript SDK Scaffold a project