Integrate/Integration

Integration overview

This section is for developers connecting software to Ether. You will authenticate, optionally submit tasks, and — for harnesses — claim work and return results.

The integration loop

your uiSubmit

POST /api/tasks→

api.tryether.aiEther OS

claim · context→

harnessExecute

steps · result↩

ws topicDeliver

Integration checklist

1. Authenticate — OTP verify → bearer token (same as ether-app).
2. Create or receive a task — POST /api/tasks or user creates one in the app.
3. Claim (harness only) — POST /api/harness/tasks/{task_id}/claim with X-Ether-Harness-App.
4. Pull context — GET /api/harness/context and per-doc MD files.
5. Execute — your model loop, git, tools (Ether does not prescribe runtime).
6. Report progress — POST .../steps and POST .../heartbeat.
7. Return outcome — POST .../result with submitted, no_changes, or blocked.
8. UI subscribes — WebSocket tasks/{task_id} for steps, interrupt, delivery.

Pull vs push execution

Model	Who starts the harness	Typical use
Pull · recommended	Harness calls claim with a known task_id	Local CLI, watch worker, explicit dispatch
Push	ether-api POSTs to your worker URL	Server-driven remote workers (ETHER_HARNESS_URL)

Most integrators should start with pull — it uses the full Harness API including delivery. See Execution modes.

Headers

Header	When
Authorization: Bearer {token}	All protected routes
X-Ether-Harness-App: your-app-id	Harness routes; identifies your integrator

Optional server gate

ETHER_HARNESS_APP_KEY must match your app id on the API.

Reference implementation

Ether Code — external repo, depends only on @ether/os-sdk:

export ETHER_API_BASE_URL=http://127.0.0.1:8080
export ETHER_TOKEN=<from OTP verify>
npm run worker -- run <task_id>

Internal engineering detail: ether-core/docs/harness-integration-guide.md (maintained alongside OpenAPI).