eClips Tech
eClipsTech

Developer Manual

REST API

The API is versioned under /v1 at https://api.eclips.tech. All responses are JSON. Authentication is a bearer API key on every endpoint except the health check; the organization is resolved from the key. List endpoints paginate with limit (max 100) and offset.

Base URL & conventions

  • Base URL: https://api.eclips.tech — all endpoints below are under /v1.
  • Auth: Authorization: Bearer eck_live_… on every endpoint except /v1/health.
  • Each endpoint enforces a scope; a key without it returns 403 Insufficient scope.
  • Pagination: limit (default 20, max 100) and offset query params.

Health

GET /v1/health — public, no authentication. Use it for uptime checks.

bash
curl https://api.eclips.tech/v1/health
json
{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-06-06T09:00:00.000Z"
}

Run an agent

POST /v1/run — scope agents:run. Body: task (required), agent_type (defaults to center), data, priority, and an optional per-run webhook_url. Returns 202 immediately with a run_id; orchestration runs asynchronously.

bash
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",
    "data": { "category": "hardware" },
    "priority": "normal",
    "webhook_url": "https://your-app.com/webhooks/eclips"
  }'
json
{
  "run_id": "a1b2c3d4-0000-4000-8000-000000000000",
  "status": "queued",
  "agent_type": "procurement_specialist",
  "estimated_completion": "async"
}
Note:An unknown agent_type or a missing task returns 400.

List & get runs

GET /v1/runs — scope agents:read. Query: status, limit, offset. Returns { data, total, limit, offset }.

bash
curl "https://api.eclips.tech/v1/runs?status=completed&limit=20&offset=0" \
  -H "Authorization: Bearer $ECLIPS_API_KEY"
json
{
  "data": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000000",
      "agent_type": "procurement_specialist",
      "status": "completed",
      "priority": "normal",
      "created_at": "2026-06-06T09:00:00.000Z",
      "started_at": "2026-06-06T09:00:01.000Z",
      "completed_at": "2026-06-06T09:00:42.000Z",
      "confidence_score": 0.94,
      "requires_triage": false,
      "error_message": null
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

GET /v1/runs/:id — scope agents:read. Returns the full run plus any linked triage item: { run, triage_item }.

bash
curl https://api.eclips.tech/v1/runs/a1b2c3d4-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $ECLIPS_API_KEY"
json
{
  "run": {
    "id": "a1b2c3d4-0000-4000-8000-000000000000",
    "agent_type": "procurement_specialist",
    "status": "completed",
    "output": { "vendors": ["Dell", "HP", "Lenovo"], "recommended": "Dell" },
    "confidence_score": 0.94,
    "requires_triage": false
  },
  "triage_item": null
}

Stream run status (SSE)

GET /v1/runs/:id/stream — scope agents:read. A Server-Sent Events stream that pushes a status update every ~2 seconds, sends a keep-alive ping every 15 seconds, and closes when the run reaches a terminal state (completed, failed, cancelled) or after a 30-second timeout.

bash
curl -N https://api.eclips.tech/v1/runs/a1b2c3d4-.../stream \
  -H "Authorization: Bearer $ECLIPS_API_KEY"

# Each event is a JSON line, pushed every ~2s:
# data: {"status":"running","confidence":null,"result":null,"error":null}
# data: {"status":"completed","confidence":0.94,"result":{...},"error":null}

Triage

GET /v1/triage — scope triage:read. Lists pending triage items (query: limit, offset), each joined to its run.

bash
curl "https://api.eclips.tech/v1/triage?limit=20&offset=0" \
  -H "Authorization: Bearer $ECLIPS_API_KEY"
json
{
  "data": [
    {
      "id": "t1r2i3a4-0000-4000-8000-000000000000",
      "run_id": "a1b2c3d4-0000-4000-8000-000000000000",
      "status": "pending",
      "triage_reason": "Amount above auto-approval threshold",
      "created_at": "2026-06-06T09:00:42.000Z",
      "agent_runs": { "id": "a1b2c3d4-...", "agent_type": "ap_specialist", "confidence_score": 0.71 }
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

POST /v1/triage/:id/approve — scope triage:write. Approves the item (body: optional resolution_note) and marks the blocked run completed.

bash
curl -X POST https://api.eclips.tech/v1/triage/$TRIAGE_ID/approve \
  -H "Authorization: Bearer $ECLIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "resolution_note": "Verified against PO — approved" }'

POST /v1/triage/:id/reject — scope triage:write. Rejects the item (body: optional reason or resolution_note) and marks the run cancelled.

bash
curl -X POST https://api.eclips.tech/v1/triage/$TRIAGE_ID/reject \
  -H "Authorization: Bearer $ECLIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Amount exceeds approved budget" }'
json
{ "data": { "id": "t1r2i3a4-...", "status": "approved", "resolved_at": "2026-06-06T09:05:00.000Z" } }

Webhooks (CRUD)

POST /v1/webhooks — scope webhooks:write. Body: url (must start with https://) and a non-empty events array. Returns 201; the signing secret is returned in the response once.

bash
curl -X POST https://api.eclips.tech/v1/webhooks \
  -H "Authorization: Bearer $ECLIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/eclips",
    "events": ["run.completed", "run.failed", "run.triage_required"]
  }'
json
{
  "data": {
    "id": "f1e2d3c4-0000-4000-8000-000000000000",
    "url": "https://your-app.com/webhooks/eclips",
    "events": ["run.completed", "run.failed", "run.triage_required"],
    "is_active": true,
    "secret": "whsec_2f4a…",
    "created_at": "2026-06-06T09:00:00.000Z"
  }
}

GET /v1/webhooks — scope webhooks:read. Lists the org's webhooks (the secret is never returned again). Returns { data: [...] }.

bash
curl https://api.eclips.tech/v1/webhooks \
  -H "Authorization: Bearer $ECLIPS_API_KEY"

DELETE /v1/webhooks/:id — scope webhooks:write. Returns { success: true }, or 404 if the webhook is not in your org.

bash
curl -X DELETE https://api.eclips.tech/v1/webhooks/$WEBHOOK_ID \
  -H "Authorization: Bearer $ECLIPS_API_KEY"
Tip:Event payloads and HMAC signature verification are covered in Webhooks.

Batches

POST /v1/batches — scope batch:run. Body: agent_type, rows[] (each { task, data? }, max 500), optional name and webhook_url. Returns 201 with { job }.

bash
curl -X POST https://api.eclips.tech/v1/batches \
  -H "Authorization: Bearer $ECLIPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "ap_specialist",
    "name": "June invoices",
    "rows": [
      { "task": "Process invoice INV-1001" },
      { "task": "Process invoice INV-1002" }
    ]
  }'
json
{
  "job": {
    "id": "b1a2t3c4-0000-4000-8000-000000000000",
    "name": "June invoices",
    "agent_type": "ap_specialist",
    "status": "pending",
    "total_rows": 2,
    "completed_rows": 0,
    "failed_rows": 0,
    "created_at": "2026-06-06T09:00:00.000Z"
  }
}

GET /v1/batches/:id — scope batch:read. Returns { job, rows } with per-row status and results.

bash
curl https://api.eclips.tech/v1/batches/$BATCH_ID \
  -H "Authorization: Bearer $ECLIPS_API_KEY"
json
{
  "job": { "id": "b1a2t3c4-...", "status": "running", "total_rows": 2, "completed_rows": 1, "failed_rows": 0 },
  "rows": [
    { "id": "...", "row_index": 0, "task": "Process invoice INV-1001", "status": "completed", "result": { "approved": true }, "error_message": null },
    { "id": "...", "row_index": 1, "task": "Process invoice INV-1002", "status": "running", "result": null, "error_message": null }
  ]
}

GET /v1/batches — scope batch:read. Lists jobs (query: status, limit, offset). Returns { jobs }.

bash
curl "https://api.eclips.tech/v1/batches?status=running&limit=20" \
  -H "Authorization: Bearer $ECLIPS_API_KEY"
json
{ "jobs": [ { "id": "b1a2t3c4-...", "name": "June invoices", "status": "running", "total_rows": 2, "completed_rows": 1, "failed_rows": 0 } ] }

POST /v1/batches/:id/cancel — scope batch:run. Cancels a pending or running job; any other state returns 400.

bash
curl -X POST https://api.eclips.tech/v1/batches/$BATCH_ID/cancel \
  -H "Authorization: Bearer $ECLIPS_API_KEY"
json
{ "cancelled": true }

Usage

GET /v1/usage — scope agents:read. Returns the org's credit summary for the current period. Companion read-only endpoints (same scope) are /v1/usage/history (last 50 ledger entries) and /v1/usage/members (per-member usage).

bash
curl https://api.eclips.tech/v1/usage \
  -H "Authorization: Bearer $ECLIPS_API_KEY"
json
{
  "plan": "team",
  "scope": "organization",
  "period": "2026-06",
  "included_credits": 50000,
  "topup_credits": 0,
  "credits_used": 12480,
  "credits_remaining": 37520,
  "unlimited": false,
  "topup_price_per_1000_usd": 5
}
Note:On an unlimited (Enterprise) plan, included_credits is -1, unlimited is true, and credits_remaining is null.
← PreviousAuthentication & ScopesNext →TypeScript SDK