Developer docs · API 2.0.0

Read the evidence, then ship an own-site fix

REST v2 gives agencies and scripts the same guarded decision core as the Eli dashboard and MCP connector. Reads identify what is pending. Writes require the exact workspace, sufficient scope and role, literal confirmation, durable limits and an audit receipt.

Open API reference MCP setup Eli AEO skill

Authentication

Send Authorization: Bearer <credential>. REST v2 accepts either a user access token or an Eli API key. Create keys in the dashboard developer settings. A new key is displayed once; Eli stores only its hash.

API key: the workspace is pinned from the validated key row. An x-eli-tenant header can only assert that same ID.
User token: reads and writes run through that user's row-level-security session. Accounts with multiple workspaces must send an exact x-eli-tenant UUID.
Scopes: keys request only read, write:own-site and/or write:drafts. Revoked, expired or creator-orphaned keys fail closed.

Read workspace resources

Call GET /api/v2/{resource}. API-key reads require the read scope.

overview

Visibility summary for the selected workspace.

competitors

Literal competitor counts from saved AI answers.

traffic

AI-referred visits grouped by source.

revenue

CRM-verified, buyer-attributed and directional evidence kept separate.

actions

Pending own-site actions and the operation that can decide each one.

prompts

Tracked buyer questions and recent model evidence.

work-log

Recent engine cycles and work events.

onsite-changes

On-site proposals; add ?id=<uuid> for a full before/after preview.

content-drafts

Content drafts; add ?id=<uuid> for the full body and publication state.

curl https://hireeli.io/api/v2/actions \
  -H "authorization: Bearer eli_live_REPLACE_ONCE"

Fetch the full diff before deciding

curl "https://hireeli.io/api/v2/onsite-changes?id=CHANGE_UUID" \
  -H "authorization: Bearer eli_live_REPLACE_ONCE"

Write with literal confirmation

The execution endpoints use the same decision core as the dashboard. The body valueconfirm: true must be the JSON boolean true. Strings such as "yes", the number 1, and free text are rejected. Always read the current resource first and ask the human to approve that exact preview.

API-key content publication requires both write:drafts and write:own-site. Dismissing a content draft requires only write:drafts; the other execution endpoints require write:own-site. For an already-published manual handoff, send provider: "manual_url" with the exact public publication_url.

POST /api/v2/onsite-changes/{id}

approve, apply, revert or dismiss an on-site change

POST /api/v2/content-drafts/{id}

approve_publish or dismiss; supports a connected CMS or verified manual URL

POST /api/v2/corrections/{id}

approve or dismiss a correction

POST /api/v2/layer/publish

publish the reviewed AI-readable layer

curl -X POST https://hireeli.io/api/v2/onsite-changes/CHANGE_UUID \
  -H "authorization: Bearer eli_live_REPLACE_ONCE" \
  -H "content-type: application/json" \
  -d '{"action":"apply","confirm":true}'

Receipts

Every accepted machine write returns a receipt. Store the whole response. The resource ID and decision tie it to the audit log; status says what actually happened; URL and revert guidance identify the next safe step; caps show the durable daily write allowance. A requested write is never reported as applied unless the execution core can verify the outcome.

{
  "decision": "apply",
  "resourceId": "CHANGE_UUID",
  "status": "applied",
  "url": "https://example.com/page",
  "revertible": true,
  "revert_hint": "Call the confirmed revert operation for this change.",
  "caps": { "used": 1, "limit": 10, "window": "day" },
  "audit_id": "AUDIT_UUID"
}

Safety and limits

Monitor plans are read-only. Paid write access follows the workspace plan and feature gates.
Protocol writes are atomically capped per workspace and UTC day; on-site weekly and content monthly business caps still apply.
Every machine decision is audited. Missing cap or audit database support makes writes unavailable rather than bypassing the check.
API and MCP can execute only own-site work. They cannot send pitches, review requests, directory submissions or other third-party outreach, and cannot switch on autopilot.
A missing or non-boolean confirmation returns HTTP 409 with required: { confirm: true } and the full current preview. Invalid bodies or actions use 400.
Rate-limit responses use HTTP 429. Authentication, role, scope, billing, conflict, content-safety and unavailable states remain distinct errors.

Agent skill

Install or copy the public Eli AEO skill into an assistant that supports agent skills. It contains the exact read → preview → confirm → approve workflow, receipt interpretation, a weekly review routine and REST v2 examples. The package is mirrored here for a future skills registry; the static files work now.

/skills/eli-aeo/SKILL.md
/skills/eli-aeo/references/workflow.md
/skills/eli-aeo/references/receipts.md
/skills/eli-aeo/references/weekly-review.md
/skills/eli-aeo/references/api.md

Public scan and published layers

The public scan requires no account and stays isolated in Eli's public tenant. Results are cached for seven days and bounded by existing public rate and cost caps.

curl -X POST https://hireeli.io/api/scan \
  -H "content-type: application/json" \
  -d '{"domain":"example.com"}'

Published customer layers remain public at /l/{slug}/llms.txt,/l/{slug}/capabilities.jsonand /l/{slug}/agents.md. These endpoints expose published material only, never private drafts.

REST v1

GET /api/v1/{resource} remains available for existing raw user-token integrations but is deprecated. New integrations should use v2 and a scoped API key. v1 never gains write methods.