Developer HubREST API · v1

API Reference

The eClips API is JSON over HTTPS. Every request is authenticated with a bearer API key and scoped to your organization. The base URL is https://api.eclips.tech.

Authentication

Pass your API key as a bearer token and your organization id in the X-Eclips-Org header. Generate keys from your dashboard . Keys are secret — never expose them in client-side code.

bash

curl https://api.eclips.tech/v1/runs \
  -H "Authorization: Bearer $ECLIPS_API_KEY" \
  -H "X-Eclips-Org: $ECLIPS_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "procurement_specialist",
    "task": "Get 3 vendor quotes for 500 laptops"
  }'

Endpoints

Runs

POST

/v1/runs

Trigger an agent run. Returns a run_id immediately.

GET

/v1/runs/:id

Fetch status and result for a single run.

GET

/v1/runs

Paginated run history for your organization.

Triage

GET

/v1/triage

List pending human-in-the-loop items.

POST

/v1/triage/:id/approve

Approve an item and continue the blocked run.

POST

/v1/triage/:id/reject

Reject an item and cancel the blocked run.

Webhooks

POST

/v1/webhooks

GET

/v1/webhooks

List all registered webhooks.

DELETE

/v1/webhooks/:id

Remove a webhook subscription.

Batches

POST

/v1/batches

Submit many tasks as a single parallel job.

GET

/v1/batches/:id

Poll a batch job and read per-row results.

GET

/v1/batches

History of batch jobs.

POST

/v1/batches/:id/cancel

Cancel rows that have not yet started.

Workflows

POST

/v1/workflows/:id/trigger

Run a saved multi-step workflow.

GET

/v1/workflows

List all saved workflows.

Example response

A POST /v1/runs returns the new run:

json

{
  "run_id": "run_a1b2c3d4",
  "status": "running",
  "agent_type": "procurement_specialist",
  "created_at": "2026-05-30T09:00:00Z"
}

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	validation_error	Request body failed validation.
401	authentication_error	Missing or invalid API key.
404	not_found	Run, triage item, or webhook does not exist.
429	rate_limited	Too many requests. Respect the Retry-After header.
5xx	server_error	Something went wrong on our side. Safe to retry with backoff.

Use the TypeScript SDK Scaffold a project