Developer reference

heyEO API docs

Use the private automation API to run the same evidence loop from CI or your own scripts. Each bearer token is bound to one project.

Private alpha

Public API: https://heyeo.io. Access remains limited to approved private-alpha projects.
On this page

API overview

Bearer-token automation, signed-in management, and public read-only surfaces.

Base URL

https://heyeo.io

Automation auth

Project-bound bearer token

Content type

application/json

API status

Private alpha · public host

  • Automation API — /api/v1/*, authenticated with a project-bound bearer token. Read scans, baselines, comparisons, management KPIs, recommendation actions and observations; create scans and drive recommendation work.
  • Token management — /api/projects/:id/automation-tokens, using your signed-in session to list, create and revoke tokens.
  • Billing — /api/workspaces/:id/billing and POST /api/stripe/webhook, owner session for Checkout and Customer Portal; webhook verifies Stripe-Signature over the raw body. Credits come from verified fulfilment only — never from a success redirect.
  • Recommendation observations — /api/projects/:id/recommendation-observations, using your signed-in session to review tracked recommendations that look actioned.
  • Site changes — /api/projects/:id/site-changes, using your signed-in session for page-level corroboration and existing deep links.
  • Onboarding assist — POST /api/onboarding/assist, using your signed-in session for the optional AI-assisted setup.
  • Public API — /api/public/*, unauthenticated and read-only, exposes only heyEO's configured public evidence projections.
  • Private and session-authenticated responses use no-store. Errors share the stable { error: { code, message } } envelope.

Authentication

Automation calls use a bearer token; management calls use your signed-in session.

An automation token looks like heyeo_v1_<12-char selector>_<43-char secret> and is sent as a bearer token:

Authorization: Bearer heyeo_v1_XXXXXXXXXXXX_your-43-character-secret

Create one under Settings → Automation tokens → Create. The full value is shown once, so store it in your secret manager. heyEO retains only a hash; if you lose the token, revoke it and create another.

API quickstart

Create a token in the app, start a scan, then poll its recorded state.

1 · Environment
# Public API origin
export HEYEO_API="https://heyeo.io"
export PROJECT_ID="123"                         # sample numeric project id — use yours
export HEYEO_TOKEN="heyeo_v1_XXXXXXXXXXXX_..."  # Settings → Automation tokens
2 · Create a scan (idempotent)
curl -X POST "$HEYEO_API/api/v1/projects/$PROJECT_ID/scans" \
  -H "Authorization: Bearer $HEYEO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "measure": true,
    "expectedPromptCount": 4,
    "providerIds": ["openai", "gemini", "perplexity"]
  }'

The response includes a runId and credit price. Reusing the same Idempotency-Key with the same body returns the original run with replayed: true and no extra charge.

3 · Poll the run
curl "$HEYEO_API/api/v1/projects/$PROJECT_ID/scans/$RUN_ID" \
  -H "Authorization: Bearer $HEYEO_TOKEN"

Run heyEO from CI/CD

A complete, retry-safe pipeline step: create a scan, poll it, and handle limits.

  1. 01

    Create a token

    In Settings → Automation tokens, create a project token with a supported expiry. The full value is shown once — store it immediately as a CI secret.

  2. 02

    Configure the environment

    Expose the API origin, project id and token to the job. The token is bound to one project.

  3. 03

    Create the scan idempotently

    Send a unique Idempotency-Key. If the network drops, retry with the same key and body to get the original run back with replayed: true and no extra charge.

  4. 04

    Poll with bounded retries

    Poll the run until its status is no longer running. On 429, wait for the Retry-After seconds and stop after a small number of attempts.

  5. 05

    Inspect the result

    Read the snapshot's result or failure, then use comparisons and management-report endpoints for deeper evidence.

  6. 06

    Rotate and revoke

    Create a replacement token, update the CI secret, then revoke the old token. Revocation takes effect for every later request.

Environment
# Store the token in your CI secret manager, never in the repository
HEYEO_API=https://heyeo.io
HEYEO_PROJECT_ID=123            # your numeric project id
HEYEO_TOKEN=${{ secrets.HEYEO_TOKEN }}
# One key per logical scan; reuse it only when retrying the same request
KEY="ci-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"

RUN_ID=$(curl -sf -X POST "$HEYEO_API/api/v1/projects/$HEYEO_PROJECT_ID/scans" \
  -H "Authorization: Bearer $HEYEO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"measure":true,"expectedPromptCount":4,"providerIds":["openai","gemini"]}' \
  | jq -r .runId)

# Poll until the snapshot is no longer running
while :; do
  STATUS=$(curl -sf "$HEYEO_API/api/v1/projects/$HEYEO_PROJECT_ID/scans/$RUN_ID" \
    -H "Authorization: Bearer $HEYEO_TOKEN" | jq -r .status)
  [ "$STATUS" != "running" ] && break
  sleep 15
done
echo "Scan $RUN_ID finished with status: $STATUS"

Token lifecycle

Active
Not revoked and before its expiry. Requests are accepted.
Expired
Past its expiry time. Requests return 401 invalid_token.
Revoked
Revoked in Settings. Requests return 401 invalid_token.

heyEO does not send outbound webhooks; pipelines poll the run until it finishes.

Use the weekly report in automations

Fetch the management report on a schedule and share an honest one-line summary.

1 · Fetch the report
curl -sf "https://heyeo.io/api/v1/projects/$HEYEO_PROJECT_ID/management-report" \
  -H "Authorization: Bearer $HEYEO_TOKEN" \
  | jq '{measuredAt, comparisonBasis, hasMoved}'
2 · Run it weekly
# GitHub Actions: every Monday at 08:00 UTC
on:
  schedule:
    - cron: "0 8 * * 1"
jobs:
  weekly-report:
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -sf "https://heyeo.io/api/v1/projects/${{ vars.HEYEO_PROJECT_ID }}/management-report" \
            -H "Authorization: Bearer ${{ secrets.HEYEO_TOKEN }}" > report.json
3 · Summarise honestly
const res = await fetch(
  `https://heyeo.io/api/v1/projects/${projectId}/management-report`,
  { headers: { Authorization: `Bearer ${process.env.HEYEO_TOKEN}` } },
);
if (res.status === 503) throw new Error("Current evidence unavailable; try after the next scan.");
const report = await res.json();

// Never present a change when nothing was compared.
const line =
  report.comparisonBasis === "none"
    ? "No baseline yet — current figures only."
    : report.hasMoved
      ? `Movement detected vs ${report.comparisonBasis}.`
      : `Stable vs ${report.comparisonBasis}.`;

// Post `line` to your team chat or append it to a spreadsheet row.

When comparisonBasis is none, there is no comparable earlier scan: report current figures only. Movement is an observed association, not proof that a change caused it.

Conventions

Behaviour shared across the automation API.

Errors

Every failure returns the same envelope with a stable code:

{
  "error": {
    "code": "insufficient_credits",
    "message": "You don't have enough credits to start this scan."
  }
}

Rate limiting

Automation tokens allow 60 requests per 60 seconds. Onboarding assist separately allows 5 requests per 60 seconds per signed-in user. A limited request returns 429 rate_limit_exceeded with a Retry-After header.

Idempotency

POST /scans requires an Idempotency-Key. The same key and body replay the original run; the same key with a different body returns 409 idempotency_conflict.

  1. Generate one unique key for each logical scan request.
  2. Keep that key when retrying the same request after a network interruption.
  3. Do not reuse it for a request with different parameters.

A safe replay returns the original run with replayed: true and does not charge again.

Project isolation

A token can see only its project. Unknown and out-of-scope resources return 404 not_found, so resources outside the project are not distinguishable.

Full status / code catalogue

StatusCodeWhen
400invalid_requestA field, query param, or the request body failed validation.
400invalid_cursorThe pagination cursor is invalid.
401invalid_tokenThe automation token is missing, malformed, unknown, expired or revoked.
401authentication_requiredA management endpoint was called without a signed-in session.
403invitation_email_mismatchSigned-in email does not match the invitation; sign in with the invited address.
403invitation_email_unverifiedSigned-in email is not confirmed; confirm the address, then open the invitation link again.
402insufficient_creditsNot enough credits to start the scan.
404not_foundThe resource does not exist, or belongs to another project (isolation).
404no_baselineNo baseline is selected for the project (comparisons).
409idempotency_conflictThe same Idempotency-Key was reused with a different payload.
409prompt_set_changedThe monitored prompt set changed between quote and reservation; re-quote.
409run_not_completeA run referenced by a comparison is not complete yet.
409token_limit_reachedThe project already has the maximum number of active tokens.
409invitation_expiredThe invitation has expired.
409invitation_revokedThe invitation was revoked and is no longer valid.
409invitation_already_acceptedThe invitation was already accepted.
409invitation_limit_reachedToo many pending invitations for the workspace; revoke one and try again.
409invalid_stateThe action is not allowed in the current state (e.g. removing a workspace owner, or a stale optimistic-lock version).
409assistance_exhaustedThe one funded AI-assisted setup has already been used for this request.
409assistance_in_progressAn AI suggestion is already being prepared (lease in progress).
405method_not_allowedHTTP method not allowed for this endpoint.
413request_too_largeThe request body exceeds 64 KiB.
415json_requiredA write request was not sent as application/json.
429rate_limit_exceededPer-token rate limit exceeded (Retry-After: 60).
502website_unreachableThe website could not be read (crawl failed).
502upstream_unavailableAI model or upstream service is temporarily unavailable (may return 503).
503service_unavailableWiring, rate limiter or auth backend is unavailable.
503queue_unavailableThe scan queue is unavailable (scan create).
503evidence_unavailableComparison evidence is unavailable for a corrupt run.
503unavailableService is temporarily unavailable (generic unavailability).
400invalid_signatureStripe webhook signature missing or verification failed.
409billing_customer_requiredNo Stripe customer is linked yet — start Checkout before opening the Customer Portal.
502checkout_failedStripe Checkout session was created without a redirect URL.
503billing_not_configuredStripe price ids are not configured for this Worker environment.
500webhook_processing_failedVerified Stripe webhook event could not be fulfilled; Stripe should retry.
500internal_errorUnexpected server error, or a response failed its own schema.

Endpoint reference

Find an endpoint

Search the verified reference or narrow it by API family and method.

Method68 endpoints

Automation API

Project-bound bearer-token endpoints for scans and evidence workflows.

GET
/api/v1/projects/{projectId}

Get project

Fetch the project's metadata: name, domain, website, markets, topics, declared ICP, providers and scan frequency.

Automation token

Response · 200

{ id, name, domain, websiteUrl, markets[], topics[], declaredIcp, createdAt, lastScanAt|null, scanFrequency (daily|weekly|monthly), providers[], workspaceId, workspaceRole (owner|member) }.

Endpoint-specific errors

StatusCodeWhen
404not_foundThe project was not found.
GET
/api/v1/projects/{projectId}/scans

List scans

List the project's scan runs, newest first, with cursor pagination.

Automation token

Query parameters

FieldTypeNotes
limitinteger1–50, default 20.
stagestringall | complete | failed. Default all.
cursorstringOpaque cursor from a previous nextCursor.

Response · 200

{ items: [{ runId, displayName, mode, pageAllowance, stage, createdAt, completedAt|null, promptCount, providerIds[], measurementPolicyVersion (legacy-model-panel-v1|retrieval-panel-v2), failure|null }], nextCursor|null }.

Endpoint-specific errors

StatusCodeWhen
400invalid_cursorThe cursor is invalid.
POST
/api/v1/projects/{projectId}/scans

Create scan

Reserve credits and queue a new scan. Idempotent: reusing the same Idempotency-Key with the same body replays the original run (replayed: true) without charging again.

Automation token

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
Idempotency-KeyrequiredstringTrimmed, 1–120 chars. Use a unique key per logical request.

Request body

FieldTypeNotes
measurerequiredbooleanMeasure the monitored prompts on the unique, non-empty providerIds selection enabled for the project.
expectedPromptCountrequiredinteger0–10. Must be > 0 when measure=true, exactly 0 when false (staleness guard).
providerIdsrequiredstring[]When measure=true, send any unique, non-empty subset of openai | gemini | perplexity | neutral that is enabled for the project. When measure=false, send [] for a crawl-only scan, or a non-empty subset to add ICP analysis without prompt measurements (site + ICP). New projects enable openai, gemini and perplexity by default; neutral is opt-in.
limitsobjectOptional crawl limits. maxPages must be an exact crawl tier: 25, 50, 100, 150, 200, or 250 (default 25). Other values return invalid_request (Unsupported crawl tier). Crawl credits for those tiers are 1–6 on the crawl_audit line. Other optional positive ints: maxResponseBytes, maxSitemapBytes, maxSitemaps, maxSitemapUrls, maxExtractedTextChars, requestTimeoutMs, maxRedirects, maxDurationMs.
Request
curl -X POST "$HEYEO_API/api/v1/projects/$PROJECT_ID/scans" \
  -H "Authorization: Bearer $HEYEO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "measure": true,
    "expectedPromptCount": 4,
    "providerIds": ["openai", "gemini", "perplexity"]
  }'

Response · 201

{ runId, reservationId, price: { billableCredits, pricingPolicyVersion, lineItems[] }, snapshot, replayed }.

{
  "runId": "8f3b...",
  "reservationId": "1a2c...",
  "price": {
    "billableCredits": 15,
    "pricingPolicyVersion": 1,
    "lineItems": [
      { "code": "crawl_audit", "label": "Crawl + audit", "billableCredits": 1, "quantity": 1, "pageAllowance": 25 },
      { "code": "icp_bundle", "label": "ICP analysis", "billableCredits": 2, "quantity": 1 },
      { "code": "prompt_measurements", "label": "Prompt measurements", "billableCredits": 12, "quantity": 12 }
    ]
  },
  "snapshot": { "runId": "8f3b...", "status": "running", "overallProgress": 0, "stages": [ /* ... */ ] },
  "replayed": false
}

Endpoint-specific errors

StatusCodeWhen
400invalid_requestMissing/invalid Idempotency-Key, body failed validation, providerIds is empty, duplicated, unsupported or not enabled for the project, or limits.maxPages is not a published crawl tier.
402insufficient_creditsNot enough credits.
409idempotency_conflictSame key, different payload.
409prompt_set_changedMonitored prompts changed since the quote; re-quote.
503queue_unavailableThe scan queue is unavailable.
GET
/api/v1/projects/{projectId}/scans/{runId}

Get scan

Poll a single scan run's live snapshot (stages, progress, status, result).

Automation token

Response · 200

A ScanRunSnapshot: { runId, stages[{ id, label, section, state, detail? }], overallProgress (0–100), status, result?, failure? }.

Endpoint-specific errors

StatusCodeWhen
404not_foundrunId is not a UUID, or the run was not found.
GET
/api/v1/projects/{projectId}/baseline

Get baseline

The project's active baseline selection plus recent baseline history.

Automation token

Query parameters

FieldTypeNotes
historyLimitinteger1–100, default 50.

Response · 200

{ active: { id, baselineRunId, selectionNumber, selectedAt }|null, history[], historyTruncated }.

POST
/api/v1/projects/{projectId}/baseline

Select baseline

Select a completed project scan as the active comparison baseline.

Automation token

Request body

FieldTypeNotes
baselineRunIdrequireduuid—
idempotencyKeyrequiredstring—

Response · 200

The persisted baseline selection.

GET
/api/v1/projects/{projectId}/comparisons

Compare runs

Compare a run against the baseline (or an explicit baseline run). Site, AI and ICP sections compare independently; a prompt/provider mismatch now returns the matching sections as partial instead of hiding every difference. A legacy-model-panel-v1 run and a retrieval-panel-v2 run never produce an AI delta. The result carries a measurement_policy_version_mismatch reason with baselinePolicyVersion and currentPolicyVersion. Select a v2 run as the new baseline.

Automation token

Query parameters

FieldTypeNotes
currentRunIdrequireduuid—
baselineRunIduuidOptional. Defaults to the project's active baseline.

Response · 200

{ baselineRunId, currentRunId, result: { status: comparable|partial|incomparable, ... } }.

Endpoint-specific errors

StatusCodeWhen
404no_baselineNo baseline is selected and none was supplied.
409run_not_completeEither run is not complete.
503evidence_unavailableA run's evidence is corrupt.
GET
/api/v1/projects/{projectId}/recommendation-actions

List recommendation actions

List recommendation actions (accepted/implemented fixes and their interventions), newest first.

Automation token

Query parameters

FieldTypeNotes
limitinteger1–50, default 20.
statestringOptional: new | accepted | implementing | implemented | dismissed.
cursorstringOpaque pagination cursor.

Response · 200

{ items: [{ ...action, sourceRecommendation: { title, summary, source, effort, affectedUrls[] }, intervention|null }], nextCursor|null }.

Endpoint-specific errors

StatusCodeWhen
400invalid_cursorThe cursor is invalid.
GET
/api/v1/projects/{projectId}/recommendation-actions/{actionId}

Get recommendation action

Full detail for one recommendation action: the source recommendation, its state-change events, and the intervention.

Automation token

Response · 200

{ action, sourceRecommendation (full), events[], eventsTruncated, intervention|null }.

Endpoint-specific errors

StatusCodeWhen
404not_foundactionId is not a UUID, or the action was not found.
POST
/api/v1/projects/{projectId}/recommendation-actions

Create recommendation action

Track one recommendation from a completed scan through implementation.

Automation token

Request body

FieldTypeNotes
sourceRunIdrequireduuid—
sourceArtifactIdrequiredinteger—
sourceRecommendationIndexrequiredinteger—
idempotencyKeyrequiredstring—

Response · 200

The created recommendation action.

POST
/api/v1/projects/{projectId}/recommendation-actions/{actionId}/transitions

Transition recommendation action

Move a recommendation action through the same state machine as the UI.

Automation token

Request body

FieldTypeNotes
toStaterequiredstring—
notesstring—
idempotencyKeyrequiredstring—

Response · 200

The updated recommendation action.

POST
/api/v1/projects/{projectId}/recommendation-actions/{actionId}/intervention

Record implementation

Record what changed and when a follow-up becomes eligible.

Automation token

Request body

FieldTypeNotes
changeUrlrequiredhttps URL—
implementedAtrequiredISO timestamp—
eligibleForFollowUpAtrequiredISO timestamp—
idempotencyKeyrequiredstring—

Response · 200

The recorded intervention.

POST
/api/v1/projects/{projectId}/recommendation-actions/{actionId}/follow-up

Attach follow-up scan

Attach an eligible completed scan as the action's follow-up evidence.

Automation token

Request body

FieldTypeNotes
followUpRunIdrequireduuid—
idempotencyKeyrequiredstring—

Response · 200

The intervention with its attached follow-up scan.

GET
/api/v1/projects/{projectId}/management-report

Get management KPIs

Return the latest evidence-backed founder scorecard and movement. The comparison basis selects a completed run at least 7 days older, else the previous completed run, else the active baseline, else none. The comparisonBasis field reports which was used: weekly_anchor | previous_run | active_baseline | none. If the current evidence is bad, returns 503. If the baseline evidence is bad, degrades to current-only (comparisonBasis: none) instead of failing.

Automation token

Response · 200

{ currentRunId, baselineRunId|null, comparisonBasis, measuredAt, hasMoved, site, aiVisibility, icp, comparisonStatus }.

Endpoint-specific errors

StatusCodeWhen
503evidence_unavailableCurrent run evidence is corrupt or unavailable.
GET
/api/v1/projects/{projectId}/recommendation-observations

List automatic detections

List automatically detected recommendation outcomes, with status and confirmation state filters.

Automation token

Response · 200

{ items: [RecommendationObservation], nextCursor|null, unresolvedCount }.

GET
/api/v1/projects/{projectId}/recommendation-observations/{observationId}

Get automatic detection

Fetch one owner- and project-scoped automatic detection.

Automation token

Response · 200

RecommendationObservation.

POST
/api/v1/projects/{projectId}/recommendation-observations/{observationId}/confirm

Confirm automatic detection

Confirm a candidate action, record its intervention and advance the linked recommendation through the same state machine as the product UI.

Automation token

Request body

FieldTypeNotes
idempotencyKeyrequiredstring—
expectedVersionrequiredinteger—

Response · 200

The updated RecommendationObservation.

POST
/api/v1/projects/{projectId}/recommendation-observations/{observationId}/suppress

Suppress automatic detection

Mark a pending detection as not this change without dismissing its recommendation.

Automation token

Request body

FieldTypeNotes
idempotencyKeyrequiredstring—
expectedVersionrequiredinteger—

Response · 200

The updated RecommendationObservation.

Token management

Create, inspect, and revoke project automation tokens from a signed-in session.

GET
/api/projects/{projectId}/automation-tokens

List automation tokens

List the project's automation tokens as safe metadata. The secret is never returned.

Signed-in session

Response · 200

{ items: [{ id, projectId, name, tokenPrefix, createdAt, expiresAt|null, lastUsedAt|null, revokedAt|null }] }.

POST
/api/projects/{projectId}/automation-tokens

Create automation token

Create a token. The full secret is returned exactly once in this response — store it now; only a hash is kept server-side.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—

Request body

FieldTypeNotes
namerequiredstringTrimmed, 1–80 chars.
expiresInDays30 | 90 | 365 | nullDefault 90. null = never expires.

Response · 201

{ token: { id, projectId, name, tokenPrefix, createdAt, expiresAt|null, ... }, secret: "heyeo_v1_..." }.

Endpoint-specific errors

StatusCodeWhen
409token_limit_reachedThe project already has the maximum active tokens.
POST
/api/projects/{projectId}/automation-tokens/{tokenId}/revoke

Revoke automation token

Revoke a token immediately. Idempotent — revoking an already-revoked token returns the same metadata.

Signed-in session

Response · 200

The revoked token summary (with revokedAt set).

Endpoint-specific errors

StatusCodeWhen
404not_foundtokenId is not a UUID, or the token was not found / not owned.

Projects

Discover the projects a signed-in user can act on: the entry point for agents and API clients.

GET
/api/projects

List projects

List every project the signed-in user can read: the project of each workspace they own or belong to, lowest id first. Agents and API clients call this once to pick a project.

Signed-in session

Response · 200

{ items: [{ id, name, domain, websiteUrl, workspaceId, workspaceRole (owner|member), lastScanAt|null }] }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredMissing, expired or unknown bearer session token.
GET
/api/projects/{projectId}

Get project (session)

Fetch one project the signed-in user can read. The shape matches the automation API's project response, including the caller's workspace role.

Signed-in session

Response · 200

{ id, name, domain, websiteUrl, markets[], topics[], declaredIcp, createdAt, lastScanAt|null, scanFrequency (daily|weekly|monthly), providers[], workspaceId, workspaceRole (owner|member) }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredMissing, expired or unknown bearer session token.
400invalid_requestThe project id is not a positive integer.
404not_foundThe project does not exist or the caller is not a member of its workspace.

Run results

Read one completed scan's recommendations, audit findings, AI visibility and ICP as a signed-in user.

GET
/api/projects/{projectId}/scan-history/{runId}/recommendations

Run recommendations

Ranked recommendations from one completed scan, with their evidence. Priority = impact × confidence ÷ effort (0–100): a planning aid, not a prediction of search, citation or revenue impact. Pass recommendationsArtifactId and an item's index to create a recommendation action.

Signed-in session

Query parameters

FieldTypeNotes
limitinteger1–50, default 25.
sourcestringsite_audit | ai_visibility | icp_drift.

Response · 200

{ runId, completedAt, status (ok|unavailable), recommendationsArtifactId|null, priorityNote, total, items: [{ index, priorityScore, title, summary, source, impact, confidence, effort, evidence[], remediation, affectedUrls[], sourceFindings? }], abstentions[], truncated }. status is unavailable when the run produced no recommendations (e.g. a crawl-only scan).

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredMissing, expired or unknown bearer session token.
400invalid_requestThe project id or a query parameter is malformed.
404not_foundThe run id is malformed, or the run does not exist in a project the caller can read.
409run_not_completeThe scan run has not completed yet.
GET
/api/projects/{projectId}/scan-history/{runId}/findings

Run audit findings

Deterministic site-audit findings from one completed scan, paginated in a stable order, with status counts for the whole run.

Signed-in session

Query parameters

FieldTypeNotes
statusstringpass | warn | fail | not_checked.
classstringissue | review | opportunity.
categorystringcrawlability | indexation | metadata | structure | answer_readiness | authority.
limitinteger1–200, default 50.
cursorstringnextCursor from the previous page.

Response · 200

{ runId, completedAt, kind: deterministic, summary: { total, pass, warn, fail, notChecked }, items: [{ findingId, checkId, title, category, status, severity, url, evidence, recommendation, findingClass|null, variant|null, familyKey|null, materialSignature|null }], nextCursor|null }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredMissing, expired or unknown bearer session token.
400invalid_requestThe project id or a query parameter is malformed.
404not_foundThe run id is malformed, or the run does not exist in a project the caller can read.
409run_not_completeThe scan run has not completed yet.
400invalid_cursorThe pagination cursor is invalid.
GET
/api/projects/{projectId}/scan-history/{runId}/visibility

Run AI visibility

Probabilistic AI-assistant answers for the run's frozen prompt set, joined to prompts and providers, with per-provider rollups. Sampled answers, not rankings or guarantees.

Signed-in session

Query parameters

FieldTypeNotes
includeMentionsbooleantrue adds each answer's brand mentions with quoted snippets. Default false.

Response · 200

{ runId, completedAt, kind: probabilistic, note, promptCount, providerIds[], summary: { answers, targetMentions, mentionRatePercent|null, averagePosition|null, abstentions, distinctCompetitors, competitorOccurrences, mentionSentiments, distinctCitationUrls, ownedCitationUrls }, providers[], competitors[] (≤25), competitorsTruncated, prompts: [{ promptId, position, text, intent, market, cells: [{ provider, model, brandMentioned, position, overallSentiment, abstained, competitors (≤10), citations (≤10), mentions? }], unmeasuredProviders[] }] }. prompts is empty for crawl-only and site+ICP scans. unmeasuredProviders lists tracks with no answer for that prompt. A track that answers without verified web-search evidence is skipped and listed here. The scan continues on the other tracks.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredMissing, expired or unknown bearer session token.
400invalid_requestThe project id or a query parameter is malformed.
404not_foundThe run id is malformed, or the run does not exist in a project the caller can read.
409run_not_completeThe scan run has not completed yet.
GET
/api/projects/{projectId}/scan-history/{runId}/icp

Run ICP

The inferred ICP for one completed scan and its comparison with the declared ICP. A crawl-only scan reuses the latest earlier ICP and says so (freshness carried_forward); that is never new evidence.

Signed-in session

Response · 200

{ runId, completedAt, kind: probabilistic, note, status (ok|unavailable), inferred|null, provenance: { freshness (measured|carried_forward), sourceRunId }|null, comparison|null, alignmentScore|null, summary: { drifting, matched, missing, extra, total, medianConfidence, dimensions[] }|null }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredMissing, expired or unknown bearer session token.
400invalid_requestThe project id or a query parameter is malformed.
404not_foundThe run id is malformed, or the run does not exist in a project the caller can read.
409run_not_completeThe scan run has not completed yet.

Scan planning

Read the prompt set a scan would measure and price a scan before starting it, as a signed-in user.

GET
/api/projects/{projectId}/prompts

List monitored prompts

The monitored prompts a measured scan would freeze right now: active, unarchived, in measurement order, capped at the pricing policy's prompt limit. Pass activeCount as expectedPromptCount when estimating or starting a measured scan.

Signed-in session

Response · 200

{ projectId, items: [{ id, text, intent, market, position }], activeCount, maxPromptCount }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredMissing, expired or unknown bearer session token.
400invalid_requestThe project id is not a positive integer.
404not_foundThe project does not exist or the caller is not a member of its workspace.
POST
/api/scans/estimate

Estimate a scan

Price a scan before starting it. Takes the same body as starting a scan and validates it the same way; never reserves, charges or claims credits. The database fixes the actual charge when the scan starts, drawn from the project owner's balance.

Signed-in session

Request body

FieldTypeNotes
projectIdrequiredstringNumeric project id.
measurerequiredbooleanMeasure the monitored prompts.
expectedPromptCountrequiredintegeractiveCount from list prompts when measuring; 0 otherwise.
providerIdsrequiredstring[]Any unique, non-empty subset of openai | gemini | perplexity | neutral enabled for the project. Empty for a crawl-only scan; non-empty with measure=false for site + ICP.
limits.maxPagesinteger25 | 50 | 100 | 150 | 200 | 250 (default 25).

Response · 200

{ price: { billableCredits, pricingPolicyVersion, lineItems[] }, selection: { projectId, measure, expectedPromptCount, providerIds[], pageAllowance }, note }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredMissing, expired or unknown bearer session token.
400invalid_requestThe body would be rejected by start scan.
404not_foundThe project does not exist or the caller is not a member of its workspace.
409prompt_set_changedMeasuring, and expectedPromptCount no longer matches the live prompt set.

Workspace collaboration

Invite members and manage workspace access.

GET
/api/workspaces/{workspaceId}/invitations

List workspace invitations

List pending invitations for the workspace. Responses use cache-control: no-store. workspaceId must be a positive decimal integer string.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token.

Response · 200

{ items: [{ id, email, role: "member", expiresAt, createdAt }] }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestworkspaceId is not a positive decimal integer.
404not_foundNo access to the workspace, or the workspace was not found.
POST
/api/workspaces/{workspaceId}/invitations

Create workspace invitation

Create a pending invitation. Role is always member. The plaintext token is returned once and never re-fetched. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token.

Request body

FieldTypeNotes
emailrequiredstringTrimmed email address, max 320 chars.

Response · 201

{ invitation: { id, email, role: "member", expiresAt, createdAt, workspaceId, selector }, token: "heyeo_inv_<24-char selector>_<secret>" }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestworkspaceId is invalid, or the email failed validation.
404not_foundNo access to the workspace, or the workspace was not found.
409invitation_limit_reachedToo many pending invitations. Revoke one and try again.
POST
/api/workspaces/{workspaceId}/invitations/{invitationId}/revoke

Revoke workspace invitation

Revoke a pending invitation. Non-UUID invitationId returns 404. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token.

Response · 200

{ workspaceId, invitationId, revoked: true }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestworkspaceId is not a positive decimal integer.
404not_foundinvitationId is not a UUID, invitation not found, or no workspace access.
POST
/api/invitations/accept

Accept workspace invitation

Accept an invitation using the one-time token, or selector+secret parts. Malformed tokens return 400 invalid_request. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token.

Request body

FieldTypeNotes
tokenstringOne-time plaintext heyeo_inv_<selector>_<secret>. Provide this OR both selector and secret.
selectorstring24-char lowercase alphanumeric selector. Required with secret when token is omitted.
secretstringInvitation secret. Required with selector when token is omitted.

Response · 200

{ workspaceId, userId, role: "owner" | "member", createdAt }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestBody missing token or selector+secret, or the token is malformed.
403invitation_email_mismatchSign in with the invited email address to accept.
403invitation_email_unverifiedConfirm your email address, then open the invitation link again.
404not_foundInvitation not found.
409invitation_revokedThis invitation is no longer valid.
409invitation_expiredThis invitation has expired.
409invitation_already_acceptedThis invitation was already accepted.
GET
/api/workspaces/{workspaceId}/members

List workspace members

List members of the workspace. Responses use cache-control: no-store. workspaceId must be a positive decimal integer string.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token.

Response · 200

{ items: [{ workspaceId, userId, role, createdAt, isCurrentUser, displayLabel }] }. displayLabel is You for the caller, Workspace owner for the owner, or Member • <last 6 of userId> otherwise.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestworkspaceId is not a positive decimal integer.
404not_foundNo access to the workspace, or the workspace was not found.
POST
/api/workspaces/{workspaceId}/members/{userId}/remove

Remove workspace member

Remove a member from the workspace. Non-UUID userId returns 404. Optional JSON body is allowed. Removing the owner returns 409 invalid_state. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token.

Response · 200

{ workspaceId, userId, removed: true }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestworkspaceId is not a positive decimal integer.
404not_founduserId is not a UUID, member not found, or no workspace access.
409invalid_stateThe workspace owner cannot be removed.

Billing

Owner-only billing, checkout, portal, and automatic top-up operations.

GET
/api/workspaces/{workspaceId}/billing

Billing summary

Owner-only billing summary for the workspace: paid entitlement, available credits, subscription projection, and the server-known offer catalogue (no Stripe price ids). Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the workspace billing owner.

Response · 200

{ workspaceId, ownerId, paidEntitled, availableCredits, purchasedBalance, hasActiveSubscription, hasStripeCustomer, subscription, offers[{id,kind,credits,label,amountCents,currency}], activity[{detailAvailable,creditSources,recentSpend}] }. Offers never include Stripe Price ids. activity.creditSources omit remaining grant balance.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestworkspaceId is not a positive decimal integer.
404not_foundCaller is not the billing owner, or the workspace was not found.
POST
/api/workspaces/{workspaceId}/billing/checkout

Create Checkout session

Owner-only. Creates a Stripe Checkout session for a server-known offer id (founding_monthly | pack_40 | pack_90 | pack_200). Client-supplied price ids are rejected. Omits payment_method_types (dynamic payment methods) and automatic_tax. Credits are never granted from the success redirect — only from the verified webhook. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the workspace billing owner.

Request body

FieldTypeNotes
offerrequiredstringOne of founding_monthly, pack_40, pack_90, pack_200.
successPathrequiredstringSame-origin path beginning with /.
cancelPathrequiredstringSame-origin path beginning with /.

Response · 200

{ sessionId, url }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestBody failed validation (unknown offer, absolute URLs, etc.).
404not_foundCaller is not the billing owner, or the workspace was not found.
503billing_not_configuredStripe price ids are not configured for this Worker environment.
502checkout_failedStripe Checkout session was created without a redirect URL.
POST
/api/workspaces/{workspaceId}/billing/portal

Create Customer Portal session

Owner-only. Opens the Stripe Customer Portal for payment methods, invoices, and cancellation. returnPath must be a same-origin path. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the billing owner.

Request body

FieldTypeNotes
returnPathrequiredstringSame-origin path beginning with /.

Response · 200

{ url }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestBody failed validation (returnPath must be a same-origin path).
404not_foundCaller is not the billing owner, or the workspace was not found.
409billing_customer_requiredNo Stripe customer is linked yet — start Checkout first.
GET
/api/workspaces/{workspaceId}/billing/auto-top-up

Get auto-top-up settings

Owner-only. Returns auto-top-up settings (enabled, threshold, pack, rolling cap, consent). Defaults when unset: disabled, 20-credit threshold, 90-credit/$10 pack, $30 rolling-30-day cap. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the workspace billing owner.

Response · 200

{ workspaceId, enabled, thresholdCredits, packCredits, rollingCapCents, consentAt, consentVersion, hasConsent }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
404not_foundCaller is not the billing owner, or the workspace was not found.
PUT
/api/workspaces/{workspaceId}/billing/auto-top-up

Update auto-top-up settings

Owner-only. Enable/disable auto-top-up and update threshold/pack/cap. Enabling without a prior consent row requires consentAcknowledged: true (records consent_at + server consent version). Never charges from this endpoint — charges happen only during admission with a saved payment method.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the billing owner.

Request body

FieldTypeNotes
enabledrequiredbooleanWhen true without prior consent, consentAcknowledged must also be true.
thresholdCreditsintegerTop up when available balance is at or below this value (default 20).
packCreditsintegerOne of 40, 90, or 200 (default 90).
rollingCapCentsintegerRolling 30-day spend safety cap in cents (default 3000).
consentAcknowledgedbooleanRequired to enable when no consent is on file.

Response · 200

{ workspaceId, enabled, thresholdCredits, packCredits, rollingCapCents, consentAt, consentVersion, hasConsent }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400consent_requiredEnabling without consentAcknowledged and no prior consent row.
400invalid_requestBody failed validation (unknown pack, out-of-range threshold/cap).
404not_foundCaller is not the billing owner, or the workspace was not found.
POST
/api/stripe/webhook

Stripe webhook

Unauthenticated. Verifies the Stripe-Signature header against the raw request body before JSON parse. Idempotent fulfilment via record_stripe_event + grant RPCs. Duplicate deliveries return 200 without double-granting. Does not invent credits on cancel/past_due — only updates subscription projection.

Public

Headers

FieldTypeNotes
Stripe-SignaturerequiredstringStripe webhook signature over the raw body.

Response · 200

{ received: true, action, duplicate }.

Endpoint-specific errors

StatusCodeWhen
405method_not_allowedOnly POST is accepted.
400invalid_requestThe raw request body could not be read.
413request_too_largeThe request body exceeds the size limit.
400invalid_signatureSignature missing or verification failed.
500webhook_processing_failedVerified event could not be fulfilled; Stripe should retry.

Scheduled scans

Read, configure, pause, and resume customer scan schedules.

GET
/api/workspaces/{workspaceId}/schedule

Get customer scan schedule

Member-readable schedule config and projected monthly credit consumption for the workspace project. Distinct from private operator suite schedules. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be a workspace member.

Response · 200

{ schedule: null | { id, workspaceId, projectId, cadence, mode, timezone, runAtLocal, dayOfWeek, dayOfMonth, pageAllowance, status, updatedAt }, projection: { isScheduled, cadence, mode, status, projectedRunsPerMonth, creditsPerRun, projectedMonthlyCredits, pricingPolicyVersion, nextRunAt, dispatchEligible } }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
404not_foundCaller is not a member, or the workspace was not found.
PUT
/api/workspaces/{workspaceId}/schedule

Create or update customer scan schedule

Owner-only upsert of daily/weekly/monthly full or crawl-only schedule with IANA timezone and local run time. Page allowance must be a configured crawl tier. Defaults to paused unless status is set. Idempotent via ON CONFLICT (project_id).

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the billing owner.

Request body

FieldTypeNotes
cadencerequiredstringdaily | weekly | monthly.
moderequiredstringfull | crawl_only.
timezonerequiredstringIANA timezone name (validated server-side).
runAtLocalrequiredstringLocal wall-clock HH:MM or HH:MM:SS.
pageAllowancerequiredintegerConfigured crawl tier (e.g. 25, 50, 100, 150, 200, 250).
dayOfWeekintegerISO weekday 1–7 required for weekly cadence.
dayOfMonthinteger1–28 required for monthly cadence.
statusstringactive | paused (default paused).
idempotencyKeystringOptional client key; upsert is naturally idempotent.

Response · 200

Same shape as GET (schedule + projection).

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestBody failed validation (cadence, timezone, page allowance, etc.).
404not_foundCaller is not the billing owner, or the workspace was not found.
POST
/api/workspaces/{workspaceId}/schedule/pause

Pause or resume customer scan schedule

Owner-only pause/resume. Pausing leaves config intact; due dispatch never fires while paused or when paid entitlement is inactive.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the billing owner.

Request body

FieldTypeNotes
pausedrequiredbooleantrue pauses; false resumes (status=active).
idempotencyKeystringOptional client key.

Response · 200

Same shape as GET (schedule + projection).

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
404not_foundNo schedule exists, caller is not the owner, or workspace not found.

Google outcomes

Connect properties, refresh imports, and read bounded outcome projections.

GET
/api/workspaces/{workspaceId}/google

Get Google connection status

Member-readable Google connection and property selection status, including whether import refresh is allowed under paid entitlement. Never returns tokens or Vault secret ids. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be a workspace member.

Response · 200

{ workspaceId, status (disconnected|connected|revoked|error), accountEmail, scopes[], connectedAt, disconnectedAt, lastErrorCode, lastErrorAt, lastImportAt, gscSiteUrl, ga4PropertyId, importAllowed }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
404not_foundCaller is not a member, or workspace not found.
POST
/api/workspaces/{workspaceId}/google/oauth/start

Start Google OAuth

Owner-only. Creates a CSRF-bound OAuth state (hashed at rest) and returns the Google authorize URL with offline access and read-only Search Console / GA4 scopes.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the billing owner.

Response · 200

{ authorizeUrl, expiresAt }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
404not_foundCaller is not the owner, or workspace not found.
503google_oauth_unconfiguredGOOGLE_OAUTH_CLIENT_ID / SECRET (and redirect) are not configured.
GET
/api/google/oauth/callback

Google OAuth callback

Consumes CSRF state, exchanges the authorization code server-side, and stores the refresh token in Vault via service-role RPC. Redirects to /app/settings with a status flag. Tokens never appear in the redirect, logs, or browser storage.

Public

Response · 302

Redirect to /app/settings?google=connected|state_mismatch|denied|error.

Endpoint-specific errors

StatusCodeWhen
GET
/api/workspaces/{workspaceId}/google/properties

List Google properties

Owner-only discovery of selectable Search Console sites and GA4 properties via the Vault-protected refresh token. Bounded to 100 entries per source, sorted deterministically. Never returns tokens or raw Google payloads.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the billing owner.

Response · 200

{ workspaceId, searchConsole[{siteUrl,permissionLevel}], ga4[{propertyId,displayName,accountDisplayName}] }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
409google_not_connectedGoogle is not connected.
409token_revokedGoogle access was revoked.
404not_foundCaller is not the owner, or workspace not found.
PUT
/api/workspaces/{workspaceId}/google/properties

Select Google properties

Owner-only selection of one Search Console site URL and/or one GA4 property id per workspace.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the billing owner.

Request body

FieldTypeNotes
gscSiteUrlstring|nullSearch Console site URL (sc-domain: or https://).
ga4PropertyIdstring|nullNumeric GA4 property id.
idempotencyKeystringOptional client key.

Response · 200

Same shape as GET /google status.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestBody failed validation.
404not_foundCaller is not the owner, or workspace not found.
POST
/api/workspaces/{workspaceId}/google/refresh

Refresh Google outcomes

Owner-only manual import. Pauses when paid entitlement is inactive (alertSignal=entitlement_inactive). Persists only allowlisted daily aggregates and top-25 pages via G9-08 RPCs. AI-referral classification is in-memory.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the billing owner.

Response · 200

{ imported, importAllowed, daysImported, lastImportAt, alertSignal (none|google_access_revoked|google_property_access_lost|google_quota_exceeded|entitlement_inactive) }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400google_properties_requiredNo GSC/GA4 property selected.
409google_not_connectedGoogle is not connected.
404not_foundCaller is not the owner, or workspace not found.
POST
/api/workspaces/{workspaceId}/google/disconnect

Disconnect Google

Owner-only. Deletes the Vault refresh token and marks the connection disconnected. Configuration and prior aggregates are retained.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be the billing owner.

Response · 200

{ status: "disconnected" }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
404not_foundCaller is not the owner, or workspace not found.
GET
/api/workspaces/{workspaceId}/google/outcomes

Google outcomes projection

Member-readable 28-day versus previous-28-day Search Console and GA4 aggregates with annotated scan/site-change dates. Copy uses observed-movement language only — no causation claims.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be a workspace member.

Response · 200

{ workspaceId, projectId, windowDays: 28, currentWindow, previousWindow, searchConsole, ga4, annotatedDates[], observedMovementNote, hasData }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
404not_foundCaller is not a member, or workspace not found.

Email

Read and update weekly digest preferences.

GET
/api/workspaces/{workspaceId}/email/digest

Get weekly digest preference

Member-readable weekly outcomes digest opt-out preference. Operational owner alerts are never suppressed by this setting. Responses use cache-control: no-store.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be a workspace member.

Response · 200

{ workspaceId, optedOut, updatedAt|null }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
404not_foundCaller is not a member, or workspace not found.
PUT
/api/workspaces/{workspaceId}/email/digest

Set weekly digest preference

Member opt-out (or opt-in) for the Monday 09:00 workspace-time weekly outcomes digest. Does not affect owner operational alerts (scan failure, skipped schedule, low credit, auto-top-up failure, revoked Google access).

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token. Caller must be a workspace member.

Request body

FieldTypeNotes
optedOutrequiredbooleantrue suppresses digests for this member.
idempotencyKeystringOptional client key.

Response · 200

{ workspaceId, optedOut, updatedAt|null }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestBody failed validation.
404not_foundCaller is not a member, or workspace not found.

Activation

Record onboarding milestones and inspect operator-only activation funnels.

POST
/api/activation/onboarding-milestones

Record onboarding activation milestones

Records registered, project_created, and onboarding_completed for the caller’s own workspace only (server-derived). Idempotent first-write-wins. Does not accept milestone names, timestamps, or workspace ids from the client.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenSigned-in Supabase session token.

Response · 200

{ workspaceId, recorded[registered|project_created|onboarding_completed] }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
404not_foundCaller has no workspace/project yet.
GET
/api/operator/activation

Operator activation funnels

Operator-allowlist only. Returns bounded activation funnel timestamps (nine fixed milestones) for recent workspaces, or a single workspace when ?workspaceId= is supplied. Never accepts arbitrary workspace ids from non-operators.

Signed-in session

Headers

FieldTypeNotes
AuthorizationrequiredBearer tokenOperator allowlisted Supabase user id.

Query parameters

FieldTypeNotes
workspaceIdstringOptional single workspace id (positive decimal integer).

Response · 200

{ items[{ workspaceId, workspaceName, projectId, projectName, milestones }] }.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
403operator_access_requiredCaller is not on the operator allowlist.

Recommendation observations

Review, confirm, or suppress detected recommendation outcomes.

GET
/api/projects/{projectId}/recommendation-observations

List recommendation observations

List tracked-recommendation evidence observations for a project. Primary founder inbox for Gate 7: candidates that look actioned after a later comparable scan. Retitled tracked copies of the same site findings collapse into one candidate (fingerprint: familyKey + materialSignature + URL); siblings already confirmed for the project (any observing run) are omitted. Page-level site changes remain corroboration only and are not required for confirmation.

Signed-in session

Query parameters

FieldTypeNotes
statusstringOptional: unchanged | evidence_changed | candidate_actioned | coverage_limited | not_evaluable.
confirmationStatestringOptional: pending | confirmed | suppressed. Inbox defaults to pending.
limitinteger1–50, default 20.
cursorstringOpaque pagination cursor.

Response · 200

{ items: [{ id, projectId, recommendationActionId, observingRunId, sourceRunId, detectorVersion, status, summary, evidence{}, confirmationState, version, detectedAt, createdAt, updatedAt, actionTitle|null, actionState|null }], nextCursor|null, unresolvedCount }. unresolvedCount is unique pending fingerprints (plus items without a fingerprint), not raw pending row count.

Endpoint-specific errors

StatusCodeWhen
400invalid_requestQuery param validation failed.
400invalid_cursorThe pagination cursor is invalid.
GET
/api/projects/{projectId}/recommendation-observations/{observationId}

Get recommendation observation

Fetch one recommendation observation by id for the authenticated owner.

Signed-in session

Response · 200

RecommendationObservation (same shape as list items).

Endpoint-specific errors

StatusCodeWhen
400invalid_requestobservationId is not a valid UUID.
404not_foundThe observation was not found, or belongs to another project.
POST
/api/projects/{projectId}/recommendation-observations/{observationId}/confirm

Confirm recommendation observation

One-click confirm that a candidate_actioned observation was intentional. Atomically records an intervention (creating one when absent), advances the recommendation through accepted → implementing → implemented with append-only events, and marks the observation confirmed. Detection alone never transitions action state. Idempotent.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—

Request body

FieldTypeNotes
idempotencyKeyrequiredstringTrimmed, 1–120 chars. Use a unique key per logical request.
expectedVersionrequiredintegerOptimistic-lock version. 409 invalid_state if stale.
changeUrlstring (URL)Optional override; defaults from observation evidence / affected URLs.
implementedAtstring (ISO-8601)Optional override; defaults to observation detectedAt.

Response · 200

The updated RecommendationObservation.

Endpoint-specific errors

StatusCodeWhen
400invalid_requestBody validation failed, or observationId is not a UUID.
404not_foundThe observation was not found, or belongs to another project.
409idempotency_conflictSame idempotencyKey, different payload.
409invalid_stateexpectedVersion was stale, observation is not pending, or status is not candidate_actioned.
POST
/api/projects/{projectId}/recommendation-observations/{observationId}/suppress

Suppress recommendation observation

Mark a pending observation as Not this change. Suppresses only that observation; does not dismiss the recommendation or transition action state. Idempotent.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—

Request body

FieldTypeNotes
idempotencyKeyrequiredstringTrimmed, 1–120 chars. Use a unique key per logical request.
expectedVersionrequiredintegerOptimistic-lock version. 409 invalid_state if stale.

Response · 200

The updated RecommendationObservation.

Endpoint-specific errors

StatusCodeWhen
400invalid_requestBody validation failed, or observationId is not a UUID.
404not_foundThe observation was not found, or belongs to another project.
409idempotency_conflictSame idempotencyKey, different payload.
409invalid_stateexpectedVersion was stale, or observation is not pending.

Site changes

Inspect and verify deterministic changes observed between scans.

GET
/api/projects/{projectId}/site-changes

List site changes

List material page changes detected between consecutive scans. Optionally filter by verification state or scope to a detecting scan via afterRunId. Returns change metadata, summary labels, unresolved count, and detecting-interval projection status when afterRunId is set.

Signed-in session

Query parameters

FieldTypeNotes
limitinteger1–50, default 20.
verificationStatestringOptional: unverified | intentional_expected | intentional_unexpected | not_mine | unsure.
cursorstringOpaque pagination cursor.
afterRunIdstring (UUID)Optional: scope to changes detected after this run. When set, response includes detectingInterval with projection status.

Response · 200

{ items: [{ id, projectId, beforeRunId, afterRunId, detectorVersion, canonicalPageUrl, changedSignals[], safeSummaries[], fingerprints{}, detectedAt, verificationState, verificationEventCount, verifiedAt|null, recommendationActionId|null, linkedAt|null, version, createdAt, updatedAt }], nextCursor|null, unresolvedCount, detectingInterval|null }. When afterRunId is supplied, detectingInterval: { afterRunId, projectionStatus (pending|completed|failed|skipped_no_baseline), unresolvedCount }; otherwise null. changedSignals: http_status | redirect_outcome | title | meta_description | canonical_url | language | robots_directives | heading_outline | structured_data | body_content.

Endpoint-specific errors

StatusCodeWhen
400invalid_requestQuery param validation failed (invalid limit, verificationState, or afterRunId UUID).
400invalid_cursorThe pagination cursor is invalid.
GET
/api/projects/{projectId}/site-changes/{changeId}

Get site change

Full detail for one detected site change: the change record, verification events, link events, suggested recommendation associations, and outcome history (later scans with comparisons).

Signed-in session

Response · 200

{ siteChange, verificationEvents: [{ id, eventNumber, fromState, verification, createdAt }], linkEvents: [{ id, eventNumber, eventKind (linked|unlinked), recommendationActionId, createdAt }], suggestedAssociations: [{ actionId, matchedUrl, matchSource (affected_url|evidence_source_url) }], outcomeHistory: { fixedBeforeRunId, entries: [{ kind (detecting_scan|later_scan), runId, completedAt|null, comparison|null, comparisonStatus }], confounders: [{ code, message, relatedSiteChangeIds[] }], observedAfterNote } }. Outcome entries max 6; comparison mirrors scan comparison structure.

Endpoint-specific errors

StatusCodeWhen
400invalid_requestchangeId is not a valid UUID.
404not_foundThe site change was not found, or belongs to another project.
POST
/api/projects/{projectId}/site-changes/{changeId}/verifications

Append site change verification

Record a founder verification (intentional_expected, intentional_unexpected, not_mine, unsure). Updates verificationState and appends a verification event. Idempotent.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—

Request body

FieldTypeNotes
verificationrequiredstringintentional_expected | intentional_unexpected | not_mine | unsure.
idempotencyKeyrequiredstringTrimmed, 1–120 chars. Use a unique key per logical request.
expectedVersionintegerOptional optimistic-lock version. When supplied, 409 invalid_state if stale.

Response · 200

The updated SiteChange record (same shape as list items).

Endpoint-specific errors

StatusCodeWhen
400invalid_requestBody validation failed, or changeId is not a UUID.
404not_foundThe site change was not found, or belongs to another project.
409idempotency_conflictSame idempotencyKey, different payload.
409invalid_stateexpectedVersion was stale (another update happened first).

Onboarding assist

Request optional, bounded AI assistance during project setup.

POST
/api/onboarding/assist

AI-assisted onboarding

One platform-funded website analysis per signed-in founder. Crawls up to 5 pages and drafts product identity plus declared ICP, competitors, and markets/topics. Founder reviews and confirms suggestions before project creation.

Signed-in session

Headers

FieldTypeNotes
Content-Typerequiredapplication/json—
AuthorizationrequiredBearer tokenSigned-in Supabase session token.
AcceptstringOptional: application/x-ndjson for streamed progress after lease acquisition.

Request body

FieldTypeNotes
websiteUrlrequiredstringHTTP(S) URL, trimmed, max 2048 chars. The only request field; product identity is drafted by the model.

Response · 200

{ assistanceId (uuid), replayed (boolean), sourceUrl, pages: { count (0–5), urls[] }, generatedAt (ISO datetime), provenance: { model, promptVersion, repaired, fallbackUsed }, product_identity (suggested with name/confidence/basis/rationale or abstained), sections: { declared_icp, competitors, markets_topics — each suggested or abstained } }. If Accept includes application/x-ndjson and lease is acquired, server may stream NDJSON progress (crawling/drafting/checking + heartbeat) then terminal result/error; otherwise plain JSON.

Endpoint-specific errors

StatusCodeWhen
401authentication_requiredNot signed in or session expired.
400invalid_requestBody validation failed or URL is invalid.
409assistance_exhaustedOne funded assist already used for a different website URL.
409assistance_in_progressLease in progress for this request.
429rate_limit_exceededMore than 5 requests in 60s for this user (Retry-After header included).
502website_unreachableCrawl failed. Check the address or enter details manually.
502upstream_unavailableAI model or upstream unavailable (may also return 503).
503service_unavailableWiring or rate limiter missing.
503unavailableService temporarily unavailable.

Public API

Unauthenticated, read-only projections for heyEO’s configured public project.

GET
/api/public/report

Get public report

Auto-latest public scan report for the configured heyEO project. Returns the newest completed scan with audit summary, inferred ICP, AEO visibility aggregates, and up to 25 recommendations. No per-scan approval—auto-published per ADR 0002. Fails closed (503) when HEYEO_PUBLIC_REPORT_PROJECT_ID is unbound.

Public

Response · 200

{ contractVersion: 1, identity: { projectName, domain }, generated: { completedAt, providerIds[], promptCount, measurementSuiteVersionId|null }, auditSummary: { total, pass, warn, fail, notChecked }, icp: null | { dimensions[{ key, values[], abstained }] }, visibility: { providers[{ provider, measuredCount, mentionCount, abstainedCount }] }, recommendations (max 25): [{ title, summary, source, effort, affectedUrls[] }] }. Providers: openai | gemini | perplexity | neutral. ICP keys: company_size | roles | industries | use_cases | pain_points | maturity | buying_triggers. Recommendation source: site_audit | ai_visibility | icp_drift. Effort: s | m | l.

{
  "contractVersion": 1,
  "identity": { "projectName": "ExampleCo", "domain": "example.com" },
  "generated": {
    "completedAt": "2026-09-10T18:30:00Z",
    "providerIds": ["openai", "gemini", "perplexity", "neutral"],
    "promptCount": 4,
    "measurementSuiteVersionId": "v2.1"
  },
  "auditSummary": { "total": 42, "pass": 30, "warn": 7, "fail": 3, "notChecked": 2 },
  "icp": {
    "dimensions": [
      { "key": "company_size", "values": ["1-10", "11-50"], "abstained": false },
      { "key": "roles", "values": ["founder", "developer"], "abstained": false }
    ]
  },
  "visibility": {
    "providers": [
      { "provider": "openai", "measuredCount": 4, "mentionCount": 3, "abstainedCount": 0 },
      { "provider": "gemini", "measuredCount": 4, "mentionCount": 2, "abstainedCount": 1 }
    ]
  },
  "recommendations": [
    { "title": "Fix missing meta descriptions", "summary": "Add descriptions to 5 pages.", "source": "site_audit", "effort": "s", "affectedUrls": ["https://example.com/about"] }
  ]
}

Endpoint-specific errors

StatusCodeWhen
405method_not_allowedNon-GET request (POST, PUT, PATCH, DELETE). Response includes Allow: GET header.
503service_unavailablePublic report is temporarily unavailable (config unbound, no completed runs, or projection failure).
GET
/api/public/evidence

Get public evidence

Approval-gated public evidence cycles for the configured heyEO project. Returns 1–10 published before/after cycles, each with a recommendation, intervention, baseline/current run provenance, and a full comparison result. Fails closed (503) when HEYEO_PUBLIC_EVIDENCE_PROJECT_ID is unbound or no cycles are approved.

Public

Response · 200

{ contractVersion: 1, identity: { projectName, domain }, cycles (1–10): [{ slug, publishedAt, recommendation: { title, summary, source, effort, affectedUrls[] }, intervention: { changeUrl, implementedAt, eligibleForFollowUpAt }, baseline: { completedAt, providerIds[], promptCount, measurementSuiteVersionId|null }, current: { ... }, comparison: { status: comparable|partial|incomparable, ... } }] }. The comparison mirrors the full scan comparison structure with finding identifiers removed. Only approved cycles are included.

Endpoint-specific errors

StatusCodeWhen
405method_not_allowedNon-GET request. Response includes Allow: GET header.
503service_unavailablePublic evidence is temporarily unavailable (config unbound, no approved cycles, or projection failure).