API reference

Base URL https://api.edgetasker.com. All /v1/* routes require an Authorization: Bearer ef_live_… header. Responses are JSON; errors use { "error": { "code", "message" } }.

GET /v1/copilot/workflows

Lists the key's active workflows (optionally for one domain) so a client — like the browser extension — can offer a picker. Each entry includes the workflow's declared inputSchema so the client can prompt for the right inputs.

GET /v1/copilot/workflows?domain=example.com

// → { "workflows": [
//      { "id", "name", "targetDomain",
//        "inputSchema": { "search_term": { "label", "required", "example" } } }
//    ] }

POST /v1/copilot/initialize

Resolves a workflow and input_data into a rendered guide protocol. Any {{token}} in a step's value or hint is interpolated from input_data; to run a workflow over a list, call initialize once per row with that row's values.

Request body

{
  "workflow_id": "wf_...",
  "input_data": { "search_term": "Wireless mouse" }
}

Response

{
  "copilot_protocol": {
    "protocolVersion": "1.0",
    "executionId": "uuid",
    "workflow": { "id", "name", "targetDomain", "version", "locale" },
    "steps": [ /* rendered steps with resolvedValue */ ],
    "missingInputKeys": [],
    "issuedAt": "ISO-8601"
  }
}

Rate limited per API key (sliding 60s window). 429 responses include a Retry-After header.

POST /v1/telemetry/log-event

Records the outcome of an execution and finalizes its ledger entry.

Request body

{
  "execution_id": "uuid",
  "workflow_id": "wf_...",
  "outcome": "completed",       // completed | manual_override | abandoned | failed
  "steps_completed": 2,
  "steps_total": 2,
  "manual_override_count": 0,
  "duration_ms": 8421,
  "observed_origin": "www.example.com"
}

A failed outcome triggers an operational alert email to your admins. Response: { "accepted": true }.

POST /v1/copilot/capture

Records values read by data-capture steps (price, stock, …) for monitoring. Response: { "accepted": true, "count": N }.

{
  "execution_id": "uuid",
  "workflow_id": "wf_...",
  "observed_origin": "www.example.com",
  "captures": [ { "key": "price", "value": "£1.20" } ]
}

POST /v1/copilot/batch

Create a batch run: a preexisting workflow bound to a list of input rows, redeemable by a token. Set the usage policy with max_runs — 1 (default) is single-use (one user, one time; e.g. a personalised list), null is unlimited (a shared run many users can execute), N allows N redemptions. Hand the returned token to the runner/user; your API key is never exposed.

{
  "workflow_id": "wf_...",
  "rows": [ { "item": "milk" }, { "item": "bread" } ],
  "max_runs": 1,               // 1 = single-use · null = unlimited · N
  "expires_in_seconds": 3600   // optional
}
// → { "batchId", "token": "efbatch_…", "rows": 2, "maxRuns": 1, "expiresAt" }

Prefer clicking? Every workflow has a 🎟️ Share a run panel in the dashboard that generates the same token from a list you type in — handy for testing the exact run before you wire this endpoint into your app.

POST /v1/batch/redeem

Redeem a batch token (no API key needed — the token is the credential). Consumes one run and returns a rendered protocol per row to iterate. Returns 410 when exhausted/expired, 404 for an unknown token.

{ "token": "efbatch_…" }

// → { "batchId", "workflow", "items": [ { "executionId", "inputData",
//      "steps": [ /* rendered */ ] } ], "runsRemaining": 0 }

Status codes