The ExpertRelay API

Getting started

1. In your workspace, open Settings → API and webhooks and make a key.
2. Send it on every request as Authorization: Bearer er_….
3. Call any endpoint below. Requests and responses are JSON.

curl https://expertrelay.ai/api/v1/week \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

Base URL: https://expertrelay.ai/api/v1/. Your workspace is the key’s workspace: an agency’s key reaches agency endpoints, an expert’s key reaches expert endpoints, and everyone has the shared ones. The machine-readable description is at openapi.json, for Postman, code generators and Zapier.

API keys

• Read only keys read everything and change nothing.
• Can make changes keys also act: add a client, reply to a help request, give customers a new version. They act straight away, with no approval step; your system has decided. Use them only where you’d trust the system with that.
• A key is shown once, when you make it. We keep only a hash of it. Revoke a key in Settings and it stops working at once; so do all of a workspace’s keys if its owner’s account is deactivated.

Responses and errors

Every response is JSON. Results include links into the app where it helps. When something can’t be done, the response has an error in plain words:

{"error": "No client matches “Acme”. list_clients shows them all."}

Clients, customers and skills can be named by email, name or id. Anything that changes a skill needs its full name, so a near miss never lands on another skill.

Everyone 20 endpoints

For agencies and experts alike.

curl https://expertrelay.ai/api/v1/needs-you \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/week \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/activity \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/answers/RUN_ID \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl -X POST https://expertrelay.ai/api/v1/answers/RUN_ID/right \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/answers/RUN_ID/correction \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "what_went_wrong": "missed_rule",
  "should_have_said": "Pause only after 7 days of data, not 3."
}'

curl -X POST https://expertrelay.ai/api/v1/help-requests/RUN_ID/rerun \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/help-requests/RUN_ID/reply \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Thanks for flagging this. Here'"'"'s the full answer.",
  "include_answer": true
}'

curl -X POST https://expertrelay.ai/api/v1/help-requests/RUN_ID/handled \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/skills \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl -X POST https://expertrelay.ai/api/v1/skills/Weekly%20ads%20triage/try \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl -X POST https://expertrelay.ai/api/v1/skills/Weekly%20ads%20triage/release \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/tries/RUN_ID \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/skills/from-session \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "personal_details_removed": true,
  "source": "Claude",
  "packet": {
    "title": "Weekly ads triage",
    "job": "Decide which ad sets to pause, scale or leave each week.",
    "method": [
      "Pull the last 14 days per ad set.",
      "Compare cost per lead with the target."
    ],
    "rules": [
      "Cost per lead over 2x target with 3+ days of data: pause."
    ],
    "examples": [
      {
        "situation": "[client], Broad ad set",
        "inputs": "CPL $84 vs $40 target, 6 days",
        "decision": "Pause Broad",
        "why": "Over twice the target with enough data."
      }
    ],
    "unsure": [
      "What to do when spend is under $500."
    ]
  }
}'

curl https://expertrelay.ai/api/v1/skills/Weekly%20ads%20triage/status \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/teach-jobs/JOB_ID \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/skills/Weekly%20ads%20triage/answers \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "answers": [
    {
      "number": 1,
      "answer": "Wait two weeks of data before pausing."
    }
  ]
}'

curl https://expertrelay.ai/api/v1/skills/Weekly%20ads%20triage/sessions \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "personal_details_removed": true,
  "packet": {
    "title": "A seasonal edge case",
    "job": "Decide which ad sets to pause, scale or leave each week.",
    "examples": [
      {
        "situation": "[client] with a seasonal spike",
        "decision": "Don'"'"'t pause during the spike week",
        "why": "Cost per lead always doubles that week and recovers."
      }
    ]
  }
}'

curl https://expertrelay.ai/api/v1/skills/Weekly%20ads%20triage/export \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/upload-link \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

Agencies 27 endpoints

Only for agency workspaces.

curl https://expertrelay.ai/api/v1/clients \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/clients \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Greenhill Physio",
  "email": "[email protected]",
  "skills": [
    "all"
  ]
}'

curl https://expertrelay.ai/api/v1/clients/owner%40acme.example \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl -X PUT https://expertrelay.ai/api/v1/clients/owner%40acme.example/skills \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "skills": [
    "Weekly ads triage",
    "Lead follow-up plan"
  ]
}'

curl -X POST https://expertrelay.ai/api/v1/clients/owner%40acme.example/invite \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/clients/owner%40acme.example/runs \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "skill": "Weekly ads triage",
  "request": "<request>"
}'

curl https://expertrelay.ai/api/v1/team-runs/RUN_ID \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/clients/owner%40acme.example/documents \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/clients/owner%40acme.example/documents \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "<title>"
}'

curl -X DELETE https://expertrelay.ai/api/v1/clients/owner%40acme.example/documents/document \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/documents \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/documents/id \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/clients/owner%40acme.example/numbers \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/compare \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/library \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/library \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "<title>"
}'

curl -X DELETE https://expertrelay.ai/api/v1/library/document \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/team \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/team/invites \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "<email>",
  "role": "admin"
}'

curl https://expertrelay.ai/api/v1/ad-accounts \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl -X PUT https://expertrelay.ai/api/v1/ad-accounts/1234567890/client \
  -H "Authorization: Bearer $EXPERTRELAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "client": "[email protected]"
}'

curl -X POST https://expertrelay.ai/api/v1/ad-accounts/1234567890/check \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/clients/owner%40acme.example/connections \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/waiting \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl https://expertrelay.ai/api/v1/connect-link \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl -X POST https://expertrelay.ai/api/v1/calls/call/file \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

curl -X POST https://expertrelay.ai/api/v1/drive/item/file \
  -H "Authorization: Bearer $EXPERTRELAY_KEY"

Webhooks

Add a webhook in Settings → API and webhooks: an https address and the events you want. We send each event as a POST with a JSON body, signed with the webhook’s secret.

What arrives

Headers: X-Expertrelay-Event, X-Expertrelay-Delivery (an id that stays the same across retries) and X-Expertrelay-Signature. The body:

{
  "id": "DELIVERY_ID",
  "event": "client.asked",
  "created_at": "2026-10-07T09:00:00+00:00",
  "data": {
    "run_id": "RUN_ID",
    "client": {
      "id": "…",
      "name": "Acme Dental",
      "email": "[email protected]"
    },
    "skill": "Weekly ads triage",
    "question": "Should we pause Broad?",
    "decision": "Pause the Broad ad set.",
    "result": "Answered",
    "answer": "**Decision:** Pause the Broad ad set. …",
    "link": "…/agency/your-agency/activity/?run=RUN_ID"
  }
}

{
  "id": "DELIVERY_ID",
  "event": "help_request.opened",
  "created_at": "2026-10-07T09:00:00+00:00",
  "data": {
    "run_id": "RUN_ID",
    "client": {
      "id": "…",
      "name": "Acme Dental",
      "email": "[email protected]"
    },
    "they_wrote": "It stopped halfway through my report.",
    "link": "…"
  }
}

{
  "id": "DELIVERY_ID",
  "event": "help_request.handled",
  "created_at": "2026-10-07T09:00:00+00:00",
  "data": {
    "run_id": "RUN_ID",
    "client": {
      "id": "…",
      "name": "Acme Dental",
      "email": "[email protected]"
    },
    "they_wrote": "It stopped halfway through my report.",
    "your_reply": "Sorry about that. Here's the full answer.",
    "link": "…"
  }
}

{
  "id": "DELIVERY_ID",
  "event": "client.added",
  "created_at": "2026-10-07T09:00:00+00:00",
  "data": {
    "client": {
      "id": "…",
      "name": "Greenhill Physio",
      "email": "[email protected]"
    }
  }
}

{
  "id": "DELIVERY_ID",
  "event": "client.connected",
  "created_at": "2026-10-07T09:00:00+00:00",
  "data": {
    "client": {
      "id": "…",
      "name": "Greenhill Physio",
      "email": "[email protected]"
    },
    "connected": "ad_accounts",
    "how": "client",
    "new": [
      {
        "platform": "Meta Ads",
        "name": "Greenhill Physio",
        "account_id": "act_1234"
      }
    ],
    "total": 1,
    "first_time": true,
    "link": "https://…/agency/…/clients/…/"
  }
}

{
  "id": "DELIVERY_ID",
  "event": "version.released",
  "created_at": "2026-10-07T09:00:00+00:00",
  "data": {
    "skill": "Weekly ads triage",
    "version": 3
  }
}

Checking a delivery is from us

X-Expertrelay-Signature: t=<unix time>,v1=<signature>. The signature is the hex HMAC-SHA256 of t. followed by the raw body, with your webhook’s secret. Compare in constant time, and reject a delivery whose t is more than 5 minutes off, so an old delivery can’t be replayed.

# Python
import hashlib, hmac, time

def from_ExpertRelay(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    sent_at = int(parts["t"])
    if abs(time.time() - sent_at) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{sent_at}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

// Node.js
const crypto = require("crypto");

function fromExpertrelay(secret, rawBody, header, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const sentAt = Number(parts.t);
  if (Math.abs(Date.now() / 1000 - sentAt) > tolerance) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${sentAt}.`).update(rawBody).digest("hex");
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Retries

• Answer any 2xx within 5 seconds and the delivery counts as done. We don’t read the response body.
• Otherwise we try again after 1 minutes, 5 minutes, 30 minutes, 2 hours, 12 hours, then give up. A webhook that keeps failing shows Failing since in Settings.
• A retry keeps the same X-Expertrelay-Delivery id: if you’ve handled it already, answer 200 and skip it.
• We only send to public https addresses, never follow redirects, and keep delivery records for 30 days. Send a test in Settings delivers a ping event straight away.

Your own AI

Prefer to ask than to code? Connect Claude or ChatGPT to your workspace in Settings → Your AI. It reads the same things as the API, and with changes allowed it can act. Anything a client or customer would see waits for you to approve it in the app. At the end of a good session, ask it to turn the session into a skill.