Agents

Agent API reference

The full operating contract for agent-led lifecycle work.

Audryo is a complete agent-first stack for lifecycle email. The API is designed so an agent can operate audiences, journeys and campaigns 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, Codex, Cursor or any MCP client, prefer the hosted MCP server at https://mcp.audryo.com/mcp with browser sign-in; for terminals and CI, the CLI from the audryo npm package (Audryo/agent-toolkit) — 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 in an MCP client connect to the hosted server https://mcp.audryo.com/mcp and sign in with OAuth 2.1 (browser consent, PKCE, workspace-bound grants). They never handle a raw token; the server exposes the same scopes as tools.

Agents and backends that call HTTP directly 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, Journey-proposal confirmation, email-revision publication, 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

Observe — load the current project context.
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.
Propose — create a versioned workflow or message proposal.
Validate — run the deterministic workflow dry run and inspect message policy output.
Review — show the Journey, emails, audience, timing and sending rules to the user. They can explicitly approve the launch in Audryo or their agent chat (including Cursor or Codex). Never infer approval from a request to prepare a draft.
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. An agent with deliver access may carry out the approved launch. Active Journeys run automatically; individual deliveries need no further human approval. Review later revisions before activating them.
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 supported claims from the active Foundation revision; 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 treat a request to draft as permission to publish or activate. After the user explicitly approves the reviewed version, use the corresponding confirmation, review and runtime operations with deliver access.
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 GET /delivery_mode first. New projects are in sandbox mode: every send runs the real pipeline but is captured in the project's Sandbox inbox (GET /sandbox_messages, GET /sandbox_messages/{id}), and POST /workflows/{id}/fast_forward skips waits. Use this to verify an entire journey end to end. Never switch a project to live; PATCH /delivery_mode pauses journeys and deletes sandbox test data, and is a human decision.
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), or with provider: smtp and an smtp object (host, port, encryption, authentication, username, password) for any other provider. SMTP identities verify by connecting and signing in and have no DNS records or delivery events; never ask for or echo SMTP passwords in chat logs. For Resend and 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.
When consent was already collected and confirmed outside Audryo (e.g. the product's own double opt-in), sync it with the ingestion field consent (action, occurredAt, source, optional evidenceReference) instead of marketingConsent. It sends no confirmation email, keeps the original timestamp and never overrides a newer ledger entry such as an unsubscribe.
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, custom SMTP) with project credentials; 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.

Update product knowledge

Read /v1/projects/{projectId}/foundation, then POST /foundation/contribute with a stable sourceKey and quoted If-Match revision token. Prefer mode: "patch" with structured ops (upsert / remove) for precise updates without AI extraction. Free-text mode: "contribute" replaces that source via extraction. A successful update activates a complete revision without individual fact approvals; write is sufficient. This does not publish or send email. Other contributions remain intact. See Foundation for source ownership, conflicts and restoration.

PreviousMCP, CLI, and skills NextAPI introduction