API reference

The public REST API under /v1, generated from the live OpenAPI 3.1 document.

Everything in the console is available through the API. The reference below is generated at request time from the OpenAPI 3.1 document this host serves at /v1/openapi.json, so it cannot drift from the API.

Conventions

Authentication: Authorization: Bearer <key> with an API key, or an OAuth 2 client-credentials token from POST /v1/oauth/token. Keys and clients carry module scopes such as graph:read or projections:write.
Versioning: send Agora-Version: 2026-10-25. Versions are dated; each is supported for 12 months after its successor ships, and older versions answer with Deprecation and Sunset headers.
Idempotency: every POST takes an Idempotency-Key. A retry with the same key and body replays the first answer for 24 hours; the same key with a different body is refused.
Errors: { "error": { "type", "code", "message", "request_id" } }. Quote the request_id when you contact support.
Lists: { "object": "list", "data", "has_more", "next_cursor" }; pass cursor to page.
Rate limits: per tenant, with X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After on a 429.

API quick-start

Create a workspace: POST /v1/signup (public) creates your tenant and first merchant and returns an API key once. Or sign up in the console at /signup.
Authenticate: Send Authorization: Bearer <key> (or an OAuth2 client-credentials token from POST /v1/oauth/token) and Agora-Version.
Connect a source: POST /v1/merchants/{mid}/connections with method csv, json, manual or a platform connector.
Publish: POST /v1/merchants/{mid}/projections/run, then GET /v1/merchants/{mid}/projections.
Listen: POST /v1/webhooks/subscriptions and verify every delivery's Agora-Signature (samples below).

SDKs

Language	Path	Install
typescript	`sdk/ts`	`npm install ./sdk/ts`
python	`sdk/python`	`pip install ./sdk/python`
php	`sdk/php`	`composer require agora/sdk`
javascript	`sdk/js-site`	`<script type="module" src="/sdk/agora-site.js">`

CLI

agora validate pack <dir>
agora validate feed <file> --surface <id>
agora validate mission <file> [--merchant <mid>]
agora publish <mid> [--surface <id>]
agora gate <mid>

Endpoint reference

188 operations, API version 2026-10-25. Machine-readable: /v1/openapi.json.

Auth

POST/v1/oauth/token

OAuth2 client credentials token

application/x-www-form-urlencoded or JSON; HTTP Basic client authentication is also accepted. Not subject to Idempotency-Key.

publiccreateToken200400

Tenant

GET/v1/tenant

The caller's tenant with billing settings, subscription and merchants

scope billing:readgetTenant200400401403429

DELETE/v1/tenant

Delete the tenant now (DSR workflow); evidence chains move to the legal-hold archive

Needs a key with full scope (*). The shared demo tenants cannot be deleted.

scope dsr:writedeleteTenant200400401403429

Parameters: confirm query, required

POST/v1/tenant/cancel

Cancel: removes connector credentials, revokes keys, schedules deletion per retention, delivers the export

Needs a key with full scope (*).

scope billing:writecancelTenant200400401403409422429

POST/v1/tenant/export

Export all tenant data (DSR workflow, scope tenant)

scope dsr:readexportTenant201400401403409422429

GET/v1/tenant/exports/{id}

A tenant export bundle

scope dsr:readgetTenantExport200400401403404429

Parameters: id path, required

Merchants

GET/v1/merchants

Merchants of the caller's tenant

listMerchants200400401403429

Parameters: limit query · cursor query

POST/v1/merchants

Create a merchant in the caller's tenant (within the plan's limit)

scope graph:writecreateMerchant201400401403409422429

GET/v1/merchants/{mid}

One merchant

getMerchant200400401403404429

Parameters: mid path, required

Onboarding

GET/v1/merchants/{mid}/connections

Connections (credential references only, never secrets)

scope connectors:readlistConnections200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/connections

Connect a source (platform connector, CSV/JSON upload or manual) and import into the graph

scope connectors:writecreateConnection201400401403404409422429

Parameters: mid path, required

GET/v1/merchants/{mid}/onboarding

The classification-first onboarding wizard and its state

scope graph:readgetOnboarding200400401403404429

Parameters: mid path, required

POST/v1/merchants/{mid}/onboarding/{step}

classify | confirm | connect | <wizard step> | publish

scope graph:writeapplyOnboardingStep200400401403404409422429

Parameters: mid path, required · step path, required

Graph

GET/v1/merchants/{mid}/entities

Business Graph entities

scope graph:readlistEntities200400401403404429

Parameters: mid path, required · limit query · cursor query · type query

GET/v1/merchants/{mid}/entities/{id}

One entity with its active overrides

scope graph:readgetEntity200400401403404429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/entities/{id}/overrides

Override one field (new graph_version, provenance api:<principal>)

scope graph:writecreateOverride201400401403404409422429

Parameters: mid path, required · id path, required

GET/v1/merchants/{mid}/validation

Validation reports per surface (completeness, errors, warnings)

scope graph:readlistValidationReports200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/graph/diff

Changes between two graph versions

scope graph:readgetGraphDiff200400401403404429

Parameters: mid path, required · from query · to query

Projections

GET/v1/merchants/{mid}/projections

Projection status per surface

scope projections:readlistProjections200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/projections/{id}/publish

Publish a projection now (409 when validation blocks)

scope projections:writepublishProjection200400401403404409422429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/projections/{id}/rollback

Roll back to the previous published version

scope projections:writerollbackProjection200400401403404409422429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/projections/run

Validate and publish every surface of the merchant

scope projections:writerunProjections200400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/projections/{id}/gate

Run release-gate missions against a staged artefact before publishing

scope lab:writerunReleaseGate200400401403404409422429

Parameters: mid path, required · id path, required

Handoff

POST/v1/merchants/{mid}/handoff-links

Mint a signed (ES256) handoff link

scope handoff:writecreateHandoffLink201400401403404409422429

Parameters: mid path, required

Lab

GET/v1/merchants/{mid}/lab/missions

Agent Lab missions

scope lab:readlistMissions200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/lab/runs

Agent Lab runs (newest first)

scope lab:readlistRuns200400401403404429

Parameters: mid path, required · limit query · cursor query · mission query

GET/v1/merchants/{mid}/lab/findings

Lab findings and fix proposals

scope lab:readlistFindings200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/lab/plans

Nightly lab plans vs budget

scope lab:readlistLabPlans200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/lab/plans

Compile an Agent Lab plan (generic missions from the graph when the packs have none)

scope lab:writecompileLabPlan201400401403404409422429

Parameters: mid path, required

GET/v1/merchants/{mid}/certificate

Current Agent-Ready certificate (signed JSON); public verification at /verify/{id}

scope lab:readgetCertificate200400401403404429

Parameters: mid path, required

POST/v1/merchants/{mid}/lab/missions/compose

Plain language -> mission DSL draft (review required)

scope lab:writecomposeMission200400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/lab/missions/compose/{draft}/accept

Accept a reviewed mission draft

scope lab:writeacceptComposedMission200400401403404409422429

Parameters: mid path, required · draft path, required

GET/v1/evidence/{token}

Shareable read-only evidence link (lab transcript or packet)

publicgetSharedEvidence200400404

Parameters: token path, required

GET/v1/lab/transparency

What AGORA lab agents do, their declared identity and disclosure

publicgetLabTransparency200400

POST/v1/lab/opt-out

Opt a site out of AGORA lab testing (honoured within 24 h)

publiclabOptOut200400

Visibility

GET/v1/merchants/{mid}/visibility/metrics

Share of answer, mention rank, citation rate, fidelity (with intervals)

scope visibility:readlistVisibilityMetrics200400401403404429

Parameters: mid path, required · limit query · cursor query · engine query · metric query · locale query

GET/v1/merchants/{mid}/visibility/panels

Visibility query panels

scope visibility:readlistVisibilityPanels200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/visibility/recommendations

Ranked recommendations

scope visibility:readlistVisibilityRecommendations200400401403404429

Parameters: mid path, required · limit query · cursor query

Kernel

GET/v1/merchants/{mid}/kernel/statements

Brand Kernel statements

scope kernel:readlistKernelStatements200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/kernel/fidelity

Description fidelity per engine and week

scope kernel:readlistKernelFidelity200400401403404429

Parameters: mid path, required · limit query · cursor query

Content

GET/v1/merchants/{mid}/content/gaps

Content gaps

scope content:readlistContentGaps200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/content/assets

Content assets

scope content:readlistContentAssets200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/campaigns

Campaign plans

scope content:readlistCampaigns200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/earned/reviews

Verified-buyer reviews and syndication (earned)

scope content:readlistReviews200400401403404429

Parameters: mid path, required · limit query · cursor query

Lifecycle

GET/v1/merchants/{mid}/consents

Agent consents (lifecycle)

scope lifecycle:readlistConsents200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/lifecycle/signals

Lifecycle signals sent to agents

scope lifecycle:readlistSignals200400401403404429

Parameters: mid path, required · limit query · cursor query

Studies

GET/v1/merchants/{mid}/studies

Synthetic studies (population-level only, R7)

scope studies:readlistStudies200400401403404429

Parameters: mid path, required · limit query · cursor query

Analytics

GET/v1/analytics/marts

Available analytics marts

listMarts200400401403429

Parameters: limit query · cursor query

GET/v1/merchants/{mid}/analytics/marts/{mart}

An analytics mart

scope analytics:readgetMart200400401403404429

Parameters: mid path, required · mart path, required

GET/v1/merchants/{mid}/readiness

Agent Readiness Score 0-100: components, pack weights, sector percentile, trend

scope analytics:readgetReadiness200400401403404429

Parameters: mid path, required

Trust

GET/v1/merchants/{mid}/trust/agents

Agent registry by tier

scope trust:readlistTrustAgents200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/trust/policies

Cedar trust policies (versioned)

scope trust:readlistTrustPolicies200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/trust/evidence-bundle

Hash-chained evidence bundle with chain verification

scope trust:readgetEvidenceBundle200400401403404429

Parameters: mid path, required

GET/v1/merchants/{mid}/agent-policy

No-code agent commerce policy: form, compiled Cedar, version

scope trust:readgetAgentPolicy200400401403404429

Parameters: mid path, required

PUT/v1/merchants/{mid}/agent-policy

Save a new policy version from the form (compiled to Cedar, never wider than the form)

scope trust:writeputAgentPolicy200400401403404429

Parameters: mid path, required

POST/v1/merchants/{mid}/agent-policy/dry-run

Evaluate requests against a draft policy, with explanations

scope trust:writedryRunAgentPolicy200400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/agent-policy/push

Push the policy to the trust edge (live within 60 s)

scope trust:writepushAgentPolicy200400401403404409422429

Parameters: mid path, required

GET/v1/merchants/{mid}/access-policy

Agent access policy document: robots.txt per assistant, Content Signals, CDN bot categories

scope trust:readgetAccessPolicy200400401403404429

Parameters: mid path, required

PUT/v1/merchants/{mid}/access-policy

Save the access choices

scope trust:writeputAccessPolicy200400401403404429

Parameters: mid path, required

POST/v1/merchants/{mid}/access-policy/publish

Publish the generated files (site SDK or CDN API)

scope trust:writepublishAccessPolicy200400401403404409422429

Parameters: mid path, required

GET/v1/merchants/{mid}/access-policy/drift

Diff between the published policy and the live site, with drift findings

scope trust:readgetAccessPolicyDrift200400401403404429

Parameters: mid path, required

GET/v1/merchants/{mid}/front-door

Agent Front Door summary: agents, accounts, actions, pending approvals, limits, delegation policy

scope trust:readgetFrontDoor200400401403404429

Parameters: mid path, required

GET/v1/merchants/{mid}/front-door/agents

Agents that acted at this business, with their accounts (principals are pseudonymous)

scope trust:readlistFrontDoorAgents200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/front-door/activity

Which agent acted for whom and did what (latest 200)

scope trust:readlistAgentActivity200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/front-door/approvals

Unified approvals queue: risky agent requests waiting for a person, with expiry

scope trust:readlistAgentApprovals200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/front-door/approvals/{id}/decision

Approve or deny a queued agent request ({ decision: approve | deny })

scope trust:writedecideAgentApproval200400401403404409422429

Parameters: mid path, required · id path, required

GET/v1/merchants/{mid}/front-door/settings

Rate and abuse limits per agent and per principal, approval expiry

scope trust:readgetFrontDoorSettings200400401403404429

Parameters: mid path, required

PUT/v1/merchants/{mid}/front-door/settings

Set the rate and abuse limits and the approval expiry

scope trust:writeputFrontDoorSettings200400401403404429

Parameters: mid path, required

POST/v1/merchants/{mid}/front-door/blocks

Block or unblock an agent or a principal ({ subject, id, blocked })

scope trust:writeblockAgentOrPrincipal200400401403404409422429

Parameters: mid path, required

Billing

GET/v1/billing/usage

Metered usage and GMV share (tiers 1-2)

scope billing:readgetBillingUsage200400401403429

Parameters: from query · to query

GET/v1/billing/plans

The plan catalogue (prices per currency, included quantities, overage, add-ons)

publiclistPlans200400

Parameters: limit query · cursor query

GET/v1/billing/subscription

Plan, status, trial, add-ons, usage against the included quantities

scope billing:readgetSubscription200400401403429

PUT/v1/billing/subscription

Change the plan, add-ons or payment method (PSP token reference only), or activate after the trial

scope billing:writeupdateSubscription200400401403429

GET/v1/billing/invoice-preview

The upcoming invoice in the tenant's billing currency with VAT lines

scope billing:readgetInvoicePreview200400401403429

Parameters: from query · to query · currency query

GET/v1/billing/invoices

Issued invoices

scope billing:readlistInvoices200400401403429

Parameters: limit query · cursor query

GET/v1/billing/settings

Billing currency, display locale, tax mode, tax country, VAT id

scope billing:readgetBillingSettings200400401403429

PUT/v1/billing/settings

Update billing currency, display locale, tax mode, tax country or VAT id

scope billing:writeupdateBillingSettings200400401403429

Webhooks

GET/v1/webhooks/subscriptions

Webhook subscriptions

scope webhooks:readlistWebhookSubscriptions200400401403429

Parameters: limit query · cursor query

POST/v1/webhooks/subscriptions

Subscribe to event families (secret returned once)

scope webhooks:writecreateWebhookSubscription201400401403409422429

DELETE/v1/webhooks/subscriptions/{id}

Delete a subscription

scope webhooks:writedeleteWebhookSubscription204400401403404429

Parameters: id path, required

POST/v1/webhooks/subscriptions/{id}/rotate-secret

Rotate the signing secret (previous secret signs too for 24 h)

scope webhooks:writerotateWebhookSecret200400401403404409422429

Parameters: id path, required

GET/v1/webhooks/deliveries

Deliveries (pending, delivered, retrying, dead_letter)

scope webhooks:readlistWebhookDeliveries200400401403429

Parameters: limit query · cursor query · status query · subscription_id query

POST/v1/webhooks/deliveries/{id}/replay

Re-send a delivery with a fresh timestamp and signature

scope webhooks:writereplayWebhookDelivery200400401403404409422429

Parameters: id path, required

Audit

GET/v1/audit/export

The tenant's audit records with chain verification (json, jsonl, cef, splunk_hec, sentinel)

scope audit:readexportAudit200400401403429

Parameters: format query · from query · to query

Status

GET/v1/status

Component status from the SLO monitors, open and recent incidents, communication templates

publicgetStatus200400

Developer

POST/v1/validate/{kind}

Validate a pack, feed artefact or mission document (the agora CLI backend)

validateDocument200400401403404409422429

Parameters: kind path, required

Packs

POST/v1/classify

URL or description -> pack proposal with confidence and suggestions (always offers the general pack)

pack.classify_business (G10, LP-09-04). Rate-limited per IP. The proposal is stored with provenance; confirm it in onboarding.

publicclassifyBusiness200400

GET/v1/packs

Pack registry: versions, status, surface declarations, display strings

listPacks200400401403429

Parameters: limit query · cursor query

GET/v1/packs/{id}

One pack with its changelog and counsel state

getPack200400401403404429

Parameters: id path, required

POST/v1/packs/validate

Pack-authoring kit validation (the CLI backend)

validatePack200400401403409422429

Notifications

GET/v1/notifications

In-app notifications of the caller's tenant

scope analytics:readlistNotifications200400401403429

Parameters: limit query · cursor query

GET/v1/notifications/subscriptions

Notification subscriptions per principal and channel

scope analytics:readgetNotificationSubscriptions200400401403429

PUT/v1/notifications/subscriptions

Set notification kinds and channels

scope analytics:writeputNotificationSubscriptions200400401403429

Reports

POST/v1/reports/jobs

Render a weekly loop, visibility week or monthly owner report (PDF or HTML, shareable link)

scope analytics:writecreateReportJob200400401403409422429

GET/v1/reports/jobs/{id}

Report job status and artefact links

scope analytics:readgetReportJob200400401403404429

Parameters: id path, required

GET/v1/reports/shared/{token}

Read-only shared report (HTML)

publicgetSharedReport200400404

Parameters: token path, required

GET/v1/reports/shared/{token}/pdf

Read-only shared report (PDF)

publicgetSharedReportPdf200400404

Parameters: token path, required

Scanner

POST/v1/scan

Public Agent Readiness Scanner: URL or name and city -> A-F grade with sub-scores

Rate-limited per IP; the same formula as the console score (LP-17-01).

publicscanBusiness200400

GET/v1/scan/{id}

A scan result

publicgetScan200400404

Parameters: id path, required

GET/v1/scan/{id}/report

The shareable scan report

publicgetScanReport200400404

Parameters: id path, required

GET/v1/scan/fixtures

Demo fixture sites the scanner grades without network

publiclistScanFixtures200400

GET/v1/prospects/{id}

Prospect pre-fill for sign-up (never returns the e-mail address)

publicgetProspect200400404

Parameters: id path, required

Trust-centre

GET/v1/trust/ai-systems

AI-system inventory (R11): role, tasks, disclosure and marking

publiclistAiSystems200400

GET/v1/trust/centre

Trust centre content generated from the system

publicgetTrustCentre200400

GET/v1/trust/attestation

Architecture attestation (payments posture)

publicgetArchitectureAttestation200400

GET/v1/trust/tpsp-matrix

Third-party service provider responsibility matrix

publicgetTpspMatrix200400

GET/v1/trust/script-posture

Script posture of the handoff page and site SDK (integrity hashes)

publicgetScriptPosture200400

GET/v1/trust/residency

Data residency per region and data class

publicgetResidency200400

GET/v1/trust/sub-processors

Sub-processors generated from deployed connectors

publiclistSubProcessors200400

GET/v1/trust/soc2

SOC 2 control mapping and observation status

publicgetSoc2Status200400

Fondaq

GET/v1/fondaq/form

Form bootstrap: signed form token, honeypot field name, consent notices (exact texts and version)

publicgetFondaqForm200400

Parameters: locale query

POST/v1/fondaq/qualify

Qualify a visitor: business (website or description) or not; scan, classification, plan, AI team, top actions, flows

Rate-limited per IP; never echoes personal data. Returns a fresh form_token that joins the qualification to the lead that follows.

publicqualifyVisitor200400

POST/v1/fondaq/leads

Leave contact details with explicit consent per channel (email, calls, WhatsApp); returns lead_id only

Needs the form_token of GET /v1/fondaq/form or POST /v1/fondaq/qualify. Contact details are sealed with the tenant key; no consent, no contact.

publiccreateFondaqLead201400

GET/v1/fondaq/unsubscribe/{token}

One-button unsubscribe page (signed token; GET changes nothing)

publicgetFondaqUnsubscribe200400404

Parameters: token path, required

POST/v1/fondaq/unsubscribe/{token}

Unsubscribe (RFC 8058 one-click List-Unsubscribe-Post, or the page button)

publicpostFondaqUnsubscribe200400404

Parameters: token path, required

Flows

GET/v1/flows

Flows of the caller's tenant (status, trigger, apps, last run)

scope flows:readlistFlows200400401403429

Parameters: limit query · cursor query · merchant_id query

POST/v1/flows

Create a flow from nodes and edges, or from a template (template_id, activate)

A flow is a draft until activated; activation validates it (one trigger, no cycles, required settings, reachable steps). Steps whose app has no credential run in simulation.

scope flows:writecreateFlow201400401403409422429

GET/v1/flows/templates

The gallery of ready flows by category, with the apps each needs

scope flows:readlistFlowTemplates200400401403429

Parameters: limit query · cursor query

GET/v1/flows/{id}

One flow with its validation issues

scope flows:readgetFlow200400401403404429

Parameters: id path, required

PUT/v1/flows/{id}

Update name, nodes or edges (a new version), status (active, paused, draft) or the kill switch

scope flows:writeupdateFlow200400401403404429

Parameters: id path, required

DELETE/v1/flows/{id}

Delete a flow (its waiting runs are cancelled)

scope flows:writedeleteFlow200400401403404429

Parameters: id path, required

GET/v1/flows/{id}/runs

Run history with per-step input and output (personal data masked)

scope flows:readlistFlowRuns200400401403404429

Parameters: id path, required · limit query · cursor query

POST/v1/flows/{id}/runs

Start a run with a payload (test: true runs with nothing leaving Fondaq)

scope flows:writestartFlowRun201400401403404409422429

Parameters: id path, required

POST/v1/flows/hooks/{token}

Inbound webhook or form for a flow (unguessable URL; optional X-Fondaq-Signature)

JSON or form-encoded, at most 64 KB. When the flow has a signing secret, X-Fondaq-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, `${t}.${body}`)> is required. Idempotency-Key, when sent, makes a repeated delivery start no second run.

publicreceiveFlowHook202400404

Parameters: token path, required

GET/v1/flows/whatsapp/{token}

WhatsApp Business webhook verification (hub.challenge)

publicverifyFlowWhatsAppHook200400404

Parameters: token path, required

POST/v1/flows/whatsapp/{token}

Inbound WhatsApp messages for a flow (X-Hub-Signature-256 with the app secret)

publicreceiveFlowWhatsAppHook200400404

Parameters: token path, required

Calls

GET/v1/calls

Calls of the caller's tenant (newest first): status, outcome, compliance record

scope calls:readlistCalls200400401403429

Parameters: limit query · cursor query · merchant_id query · status query · goal query · direction query

POST/v1/calls

Place an outbound AI call (goal, consent_ref); refused without consent, outside the calling window, on the do-not-call list or over budget

The agent says it is automated in its first line (R11). Simulated end to end until a phone provider (Twilio, Telnyx, Vonage) is connected; a refused call answers 200 with status refused and the reason.

scope calls:writeplaceCall201400401403409422429

GET/v1/calls/{id}

One call: transcript, structured outcome (result, summary, next step, booking, promised payment), compliance record

scope calls:readgetCall200400401403404429

Parameters: id path, required

POST/v1/calls/consents

Record a person's consent to calls (the business attests it collected it); returns the consent_ref

scope calls:writerecordCallConsent201400401403409422429

POST/v1/calls/do-not-call

Put a number on the do-not-call list (stored as a hash)

scope calls:writeaddDoNotCall201400401403409422429

GET/v1/calls/agents

The AI call agents of a business

scope calls:readlistCallAgentsAlias200400401403429

Parameters: limit query · cursor query · merchant_id query, required

PUT/v1/calls/agents/{id}

Change a call agent

scope calls:writeupdateCallAgentAlias200400401403404429

Parameters: id path, required

GET/v1/merchants/{mid}/posts

Social posts of a business (calendar order): state, captions per language, gate and AI-marking summary

scope social:readlistPosts200400401403404429

Parameters: mid path, required · limit query · cursor query · state query · from query · to query

POST/v1/merchants/{mid}/posts

Draft a post on a connected channel (AI-composed, or your own captions); it waits for approval unless the channel auto-publishes

Body: channel_id or network, theme, format, offering_id, scheduled_at, captions [{ locale, text }]. Every post passes the Brand Kernel gate (R6), carries an AI-content marking manifest and the in-caption declaration (R11), and posts about restricted offerings are gated per audience market (R12). Channels without a credential are simulated.

scope social:writecreatePost201400401403404409422429

Parameters: mid path, required

GET/v1/merchants/{mid}/posts/{id}

One post

scope social:readgetPost200400401403404429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/posts/{id}/approve

Approve a post: it is scheduled, or published at once when its time has come (the gates run again first)

scope social:writeapprovePost200400401403404409422429

Parameters: mid path, required · id path, required

GET/v1/merchants/{mid}/ad-campaigns

Ad campaigns across platforms: status, budget, spend and results (/campaigns are the growth campaign plans)

scope ads:readlistAdCampaigns200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/ad-campaigns

Create a campaign from a goal (goal, budget_minor, daily_minor, markets, radius_km, platforms): a draft that waits for approval

Restricted categories are refused per pack, per compliance (vertical controls, permits, R12 jurisdiction gate per market) and per platform rules. Creatives pass the kernel gate and carry an AI-content marking. Nothing is spent until the campaign is launched.

scope ads:writeplanAdCampaign201400401403404409422429

Parameters: mid path, required

GET/v1/merchants/{mid}/ad-campaigns/{id}

One ad campaign: placements, creatives, performance in plain numbers

scope ads:readgetAdCampaign200400401403404429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/ad-campaigns/{id}/launch

Approve and launch a campaign inside the spending limits (refused while the kill switch is on)

scope ads:writelaunchAdCampaign200400401403404409422429

Parameters: mid path, required · id path, required

GET/v1/merchants/{mid}/ads/guard

Spending limits (monthly cap, daily limit, approval threshold), spend so far and the kill switch

scope ads:readgetAdsGuard200400401403404429

Parameters: mid path, required

POST/v1/merchants/{mid}/ads/kill-switch

Stop (engaged: true) or release (engaged: false) all ad spending at once

scope ads:writesetAdsKillSwitch200400401403404409422429

Parameters: mid path, required

Agents

POST/v1/architect

Business Architect: a description, website, goal or idea -> the AI team to hire, the apps to connect in order, the flows to turn on, first steps

Public and rate-limited per address; no personal data is echoed. Attributed to Fondaq's own tenant through the llm-gateway (task agents.architect, R14); the deterministic stand-in serves it unless a provider is configured. The plan id can be applied after sign-up.

publicgetArchitectPlan200400

GET/v1/agents

The AI team of the caller's tenant across its businesses (filter with merchant_id): status, missing apps, flows, guardrails

scope agents:readlistTenantAgents200400401403429

Parameters: limit query · cursor query · merchant_id query

GET/v1/agents/{id}

One AI team member of the tenant

scope agents:readgetAgent200400401403404429

Parameters: id path, required

PUT/v1/agents/{id}

Change an AI team member: guardrails (approvals, monthly cap, quiet hours, consent channels) and status (paused or active)

scope agents:writeupdateAgent200400401403404429

Parameters: id path, required

GET/v1/agents/definitions

The AI team members a business can hire: role, name, avatar, goals, KPIs, apps, flow templates, guardrails

publiclistAgentDefinitions200400

Parameters: limit query · cursor query

GET/v1/merchants/{mid}/agents

The business's AI team: status (active, setup, paused), missing apps, flows, guardrails

scope agents:readlistHiredAgents200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/agents

Hire an AI team member ({ definition_id }); its flows are drafted and turn on once their apps are connected

scope agents:writehireAgent201400401403404409422429

Parameters: mid path, required

DELETE/v1/merchants/{mid}/agents/{id}

Remove an AI team member (its flows are switched off; their history is kept)

scope agents:writefireAgent200400401403404429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/agents/{id}/pause

Pause an AI team member (its flows and phone goals stop)

scope agents:writepauseAgent200400401403404409422429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/agents/{id}/resume

Resume an AI team member

scope agents:writeresumeAgent200400401403404409422429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/architect

Business Architect for this business (attributed to the tenant's budget, R14)

scope agents:writeplanForMerchant200400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/architect/apply

Set a plan up ({ plan_id }): hires its agents, drafts their flows, lists the apps still to connect

scope agents:writeapplyArchitectPlan200400401403404409422429

Parameters: mid path, required

Service

POST/v1/merchants/{mid}/service/order_status

Status of an order or booking: timeline, refunds, returns, cases and the actions its policies still allow

Body: reference (order id, order number or booking id), optional customer_ref, and the action's fields (or details). Every outcome answers a ServiceResult { ok, action, status, code, message, data, evidence_id }: 200 done, 202 pending_approval, 409 refused / fee_acceptance_required / not_applicable, 404 unknown record. Policies come from the business's graph; money moves only through the PSP. order_status and invoice need no Idempotency-Key.

scope service:readgetServiceStatus200400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/service/reschedule

Move a booking (slot_id, party) within its policy snapshot's modification window

scope service:writerescheduleBooking200400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/service/cancel

Cancel an order (refund through the PSP that captured it) or a booking (deposit refunded or retained per policy; accept_fee confirms a fee)

scope service:writecancelOrderOrBooking200400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/service/return

Authorise a return (items, reason) under the returns policy (window, deductions); the refund follows receipt

scope service:writeauthoriseReturn200400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/service/invoice

Invoice of an order or booking from commerce data, with signed HTML and PDF links

scope service:readgetServiceInvoice200400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/service/support_case

Open a support case (topic, text): a case record, an in-app notification and the support_case.opened flow trigger

scope service:writeopenSupportCase200400401403404409422429

Parameters: mid path, required

GET/v1/merchants/{mid}/service/cases

Support cases (newest first)

scope service:readlistSupportCases200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/service/returns

Return authorisations and their refunds (newest first)

scope service:readlistServiceReturns200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/service/returns/{id}/receive

The returned items arrived: the refund is issued through the order's PSP (or recorded as settled by the business)

scope service:writereceiveServiceReturn200400401403404409422429

Parameters: mid path, required · id path, required

GET/v1/merchants/{mid}/service/approvals

Service requests waiting for (or decided by) a person

scope service:readlistServiceApprovals200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/service/approvals/{id}/approve

Approve a pending service request: it runs once

scope service:writeapproveServiceRequest200400401403404409422429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/service/approvals/{id}/reject

Decline a pending service request

scope service:writerejectServiceRequest200400401403404409422429

Parameters: mid path, required · id path, required

GET/v1/merchants/{mid}/service/activity

Which agent did which service action for whom (pseudonymous principals), with the evidence record

scope service:readlistServiceActivity200400401403404429

Parameters: mid path, required · limit query · cursor query

Concierge

POST/v1/merchants/{mid}/concierge/converse

One grounded concierge turn: an answer from the business's approved facts with citations, the AI disclosure, and real actions (availability, holds, quotes, checkout handoff, sign-up, contact requests with consent, post-purchase service)

Body: { message, history?, locale?, context?: { session_id, jurisdiction, offering_id, action: { type, payload }, input: { contact, consent, name, reference } } }. Answers come from Fondaq's own model only after it passes the concierge evaluation, otherwise from the deterministic grounded composer; never from a hosted third-party model. Every number is verified against a cited fact.

scope concierge:readconciergeConverse200400401403404409422429

Parameters: mid path, required

GET/v1/merchants/{mid}/concierge/conversations

The assistant's conversation log (personal data masked)

scope concierge:readlistConciergeConversations200400401403404429

Parameters: mid path, required · limit query · cursor query

GET/v1/merchants/{mid}/concierge/settings

Website assistant settings and the install snippet

scope concierge:readgetAssistantSettings200400401403404429

Parameters: mid path, required

PUT/v1/merchants/{mid}/concierge/settings

Change the website assistant (enabled, allowed origins, greeting, position, accent, contact form)

scope concierge:writeupdateAssistantSettings200400401403404429

Parameters: mid path, required

GET/v1/merchants/{mid}/concierge/pages

The business's own pages the assistant may quote (pending until approved)

scope concierge:readlistAssistantPages200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/concierge/pages

Add a page of the business's own site ({ url, title?, text | html }) or import one ({ import_url }) through the scanner's guarded fetcher

Pages must be on the business's own domains; imports honour robots.txt and Content Signals (ai-input=no is refused) and fetch the live site only with AGORA_SCANNER_LIVE=1. A page is used for answers only after approval.

scope concierge:writeaddAssistantPage201400401403404409422429

Parameters: mid path, required

POST/v1/merchants/{mid}/concierge/pages/{id}/approve

Approve a page for answers (a newer version of the same URL replaces the older one)

scope concierge:writeapproveAssistantPage200400401403404409422429

Parameters: mid path, required · id path, required

DELETE/v1/merchants/{mid}/concierge/pages/{id}

Remove a page from the assistant's sources

scope concierge:writeremoveAssistantPage200400401403404429

Parameters: mid path, required · id path, required

Journeys

GET/v1/merchants/{mid}/journeys

Guided paths on the business's website (trigger, steps, A/B variant, status, checks)

scope journeys:readlistJourneys200400401403404429

Parameters: mid path, required · limit query · cursor query

POST/v1/merchants/{mid}/journeys

Create a journey from { name, trigger, steps, variant_b?, split? }, or draft one from { goal } (AI-drafted, never live before approval)

scope journeys:writecreateJourney201400401403404409422429

Parameters: mid path, required

GET/v1/merchants/{mid}/journeys/{id}

One journey with its draft, its live version and its checks

scope journeys:readgetJourney200400401403404429

Parameters: mid path, required · id path, required

PUT/v1/merchants/{mid}/journeys/{id}

Edit the draft; the approved version keeps serving until the next approval

scope journeys:writeupdateJourney200400401403404429

Parameters: mid path, required · id path, required

DELETE/v1/merchants/{mid}/journeys/{id}

Archive a journey (it stops serving)

scope journeys:writedeleteJourney200400401403404429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/journeys/{id}/approve

Approve the draft: copy, offering and conversion checks run, then it goes live

422 checks_failed lists what blocks it (a prohibited term, an unapproved claim, a number no fact states, an offering the jurisdiction gate withholds, a booking step for a business without bookings).

scope journeys:writeapproveJourney200400401403404409422429

Parameters: mid path, required · id path, required

POST/v1/merchants/{mid}/journeys/{id}/pause

Stop serving a live journey (resume by approving or from the console)

scope journeys:writepauseJourney200400401403404409422429

Parameters: mid path, required · id path, required

GET/v1/merchants/{mid}/journeys/{id}/results

Shown, engaged, converted and dismissed per variant, and the sequential A/B test (lift, interval, always-valid p, decision)

scope journeys:readgetJourneyResults200400401403404429

Parameters: mid path, required · id path, required

Source: docs/portal/docs/api.md + GET /v1/portal (generated from /v1/openapi.json)

API reference

Conventions

API quick-start

SDKs

CLI

Endpoint reference

Auth

Meta

Signup

Tenant

Merchants

Onboarding

Graph

Projections

Handoff

Lab

Visibility

Kernel

Content

Lifecycle

Studies

Analytics

Trust

Billing

Webhooks

Audit

Status

Developer

Packs

Notifications

Reports

Scanner

Trust-centre

Fondaq

Flows

Calls

Social

Ads

Agents

Service

Concierge

Journeys