Agent API reference

Audryo is designed so an agent can operate the product without browser automation. The frontend is one client of the Rails API; it has no privileged domain logic.

Discover

GET /v1/agent_manifest
GET /v1/openapi
GET /v1/bootstrap

The manifest describes the operating model, context endpoints, proposal actions, and review policy. OpenAPI is the authoritative request and response contract. A browsable index of human docs lives at /llms.txt. For Claude, Cursor, or a terminal, prefer the packaged MCP server and CLI in packages/audryo — see Agent packaging.

The setup context is the authoritative first-run path for both UI and agents: Foundation → Data → Audience → Opportunity → Journey → Message → Sending → Launch. Do not infer project readiness from the presence of a Journey alone.

Authenticate

Agents use a workspace-bound Bearer token:

Authorization: Bearer sf_live_...

Workspace owners and admins create tokens in the product at /settings/agents. The raw secret is returned exactly once. Available scopes:

• read — inspect contexts and reviewable records.
• write — create and update project resources.
• deliver — consent, suppressions, activation, campaign/transactional send.

A token never inherits access to another workspace. Use separate credentials when an agent operates multiple workspaces.

Workspace-admin agents can also operate the administrative surface:

GET    /v1/workspaces/{workspaceId}/memberships
POST   /v1/workspaces/{workspaceId}/invitations
PATCH  /v1/workspaces/{workspaceId}/memberships/{membershipId}
GET    /v1/workspaces/{workspaceId}/audit_events

Creating an invitation sends an operational email and is therefore an external side effect. Use a stable upstream task identifier and surface the result to the operator. Audit records attribute Bearer mutations to the exact API token.

Operating loop

1. Observe — load the current project context.
2. Decide — inspect evidence and the highest-ranked opportunity. Funnel

gaps (did event A, not B after 14 days, no active journey on B) are ranked by eligible × conversion gap. The candidate list is never an LLM output.

1. Propose — create a versioned workflow or message proposal.
2. Validate — run the deterministic workflow dry run and inspect message

policy output.

1. Review — surface the proposal to a human. Never infer approval.
2. Launch — after human approval, a passing dry run and a confirmed Message,

update the Journey runtime to active. Rails evaluates the current Audience, creates idempotent enrollments and re-evaluates governance immediately before every send.

1. Learn — use conversion and holdout results from measurement context.

Opens and clicks are diagnostics; product conversions and incremental lift remain the primary outcomes. When Brief flags a journey losing to holdout, propose_from_finding creates a review-only graph revision from that diagnosis — not a rewritten email. Winning or still-collecting journeys are leave_it. The live journey stays unchanged. Planner and email copy may state only confirmed product facts; wait-until timeouts are sized from ingest P90 when enough events exist.

First connection: a safe data handoff

An integration agent begins with read and write, never deliver. It first reads the manifest and the project setup/data contexts, then may sync bounded contact batches through POST /v1/projects/{projectId}/contact_ingestion and product events through POST /v1/projects/{projectId}/event_ingestion.

Every record needs a stable external ID. Ingestion can create or update data definitions, but those definitions remain reviewable: an agent must not mark an ambiguous business signal as confirmed. It must not infer marketing consent from a contact, import or event. After sync, it reloads /data_context, proposes audiences only from confirmed signals, and lets Audryo surface a grounded opportunity for human review.

For one person, read GET /v1/projects/{projectId}/contacts/{contactId} as the Contact 360 context. It combines profile properties, journey membership, unique and total message engagement, privacy-safe click destinations, product activity, consent evidence and one chronological timeline. Agents should not reconstruct this history from unrelated collections.

For one Message, read GET /v1/projects/{projectId}/message_documents/{messageId}/recipients. The cursor-paginated report can be searched and filtered by sent, delivered, opened, clicked or failed activity. Each row links the recipient to its Contact 360 context and Journey; agents should follow the cursor instead of requesting an unbounded delivery export.

For portfolio-level decisions, read GET /v1/projects/{projectId}/performance_context?range=30d. The deterministic context returns delivery and engagement rates, product conversions, ranked Journeys and Messages, and operational issues for 7d, 30d, 90d or all. Use the measurement context alongside it when treatment-versus-holdout incrementality is required.

Safe mutation rules

• Scope every domain call through projectId.
• Request only the token scopes needed for the task.
• Send a stable Idempotency-Key on LLM-backed proposal calls, test deliveries,

workflow enrollments, campaign send, and transactional send. Reusing the key returns the first successful response and does not repeat the side effect.

• Treat all generated objects as inactive proposals.
• Revise message content only through the revision operation. It creates a new

immutable version, reruns schema and claim policy checks, renders HTML/plain text and returns the proposal to review.

• Read the journey version history before reverting configuration. Restore

creates a new version in the same lineage, archives the current runtime version and requires dry run and approval again.

• Select the exact workflowId for message generation. The message context

exposes audience, objective, message goals and review state for that choice; never default silently to the first journey.

• Before drafting a localized email, read the Project's supportedLocales and

defaultLocale. Draft only an enabled locale. A Journey can launch only when every enabled locale has a confirmed variant for every email step; a contact's language is used only when it is enabled, otherwise delivery uses the project default.

• Do not send raw contact records to LLM endpoints.
• Do not translate confirmed, approved or active from natural-language

intent. Use the explicit review operations.

• Keep test delivery separate from workflow publication.
• Treat PATCH /workflows/{workflowId}/runtime as a delivery mutation. It

requires the deliver scope. Activation evaluates the current Audience; pausing exits scheduled work and prevents queued jobs from sending. Contact and event ingest, inbound webhooks, and Journey activation enroll matching contacts immediately. Outbound webhook destinations receive signed email.*, contact.updated and journey.* events asynchronously; a failing destination is retried and never blocks sending. The 15-minute Solid Queue audience poll is a catch-up safety net for CSV imports and missed webhooks; the lineage-based entry key prevents duplicate enrollment. Activation fails closed when no sending identity is configured.

• Read /delivery_context before launch. If no project identity is verified,

create it through POST /sending_identity with the project's own ESP API key (provider: resend recommended, or mailgun). Surface the returned DKIM records to the operator and poll POST /sending_identity/refresh. An agent may manage sender metadata and verification checks, but it must never claim that a DNS change was applied or verified before Rails reports status: verified. Audryo does not send customer mail from its own mail servers.

• Never place credentials or customer payloads into audit metadata.
• Treat contact erasure as irreversible. It requires explicit confirmation,

is audited and retains only an anonymous suppression digest.

• Set marketingConsent: true while creating a contact only when the caller has

verifiable permission evidence. Omit it or set it to false otherwise; the platform never infers marketing consent from contact creation.

• Check the project's requireDoubleOptIn flag before assuming marketingConsent: true

grants consent immediately. When it's on, the ledger records a pending event and the platform emails a confirmation link; the contact's status stays pending (not marketable) until the recipient confirms.

• Read a field or event definition before deleting it. The usage response lists

affected audiences and journeys; deleting an in-use signal requires confirmUsage: true.

• Build audiences only from the documented declarative rule and group schema.

Nested groups are limited to three levels and 25 leaf rules; preview the audience before persisting or using it in a journey.

• Set every Journey communicationClass explicitly. Supported classes are

marketing, newsletter, product_service, operational and transactional. Keep the consent guard class identical: Rails rejects a mismatch. Marketing and Newsletter require a matching grant; every class remains subject to global bounce and complaint suppressions.

Current capability surface

• Product source ingestion and evidence review
• Authoritative first-run progress and next action for every project
• Audited, retry-safe project-neutral sample data for evaluation
• Contact/event metadata ingestion and semantic capability review
• Deterministic integration health, data-quality issues and lifecycle readiness
• Signed inbound webhooks for immediate contact/event ingest and journey enrollment
• Signed outbound webhook destinations for email and journey lifecycle events,

with bounded retries, a delivery log, and fail-closed secret rotation

• Immutable field and event change histories with actor and before/after values
• Deterministic setup-incomplete opportunity detection
• Versioned workflow proposals and dry runs
• Public-source Brand Kits
• Structured, grounded Message Documents
• Desktop, mobile and plain rendering
• Audited test delivery and transactional send
• Append-only consent ledger, optional per-project double opt-in, and immediate

suppressions / blocklists

• Approved, idempotent and scheduled workflow enrollments
• Self-service ESP providers (Resend default, Mailgun) with project API keys;

platform SES legacy-only

• Project-scoped sending-domain onboarding with copyable DKIM records, sender

metadata (including optional CC/BCC) and explicit provider verification

• Agent-readable delivery readiness and product-measurement contexts
• Contact 360 profiles with journey membership and a unified message, product

and consent timeline

• Signed open/click tracking with unique and total engagement aggregates
• Privacy-safe click destinations plus bounce and complaint signals
• Searchable, cursor-paginated Message recipient reports with engagement filters
• Range-aware project performance with Journey and Message rankings
• Audited Journey activation, pause, audience evaluation and runtime metrics
• Deterministic workflow holdouts and incremental conversion reporting

Project sending identities are self-service and fail closed until the provider verifies their DKIM records. Customer mail always leaves through the connected ESP.