Guide
Safety, approvals, webhooks, and recovery
Atlas API integrations should preserve Mirai invariants: server-derived tenant identity, least-privilege scopes, tool-mediated business writes, idempotent requests, auditability, and outbox-safe outbound effects.
Dry-run and shadow execution
Use preview or shadow modes before live writes when testing action payloads. Treat support for a specific action as contract-driven: if the OpenAPI contract does not list a dry-run or shadow field for that action, do not assume it exists.
Approvals and human gates
Risky actions should create an approval request or operator handoff instead of executing silently. This protects payment-like, loyalty, voucher, booking, and customer-impacting workflows.
Evidence-backed knowledge search
Use Atlas Knowledge results with source metadata to ground replies. If no evidence supports an answer, the agent should ask for clarification or hand off rather than inventing policy.
Outbox-safe messaging
Outbound customer messages should flow through Mirai-managed delivery paths. Agents should not bypass the outbox or write provider state directly.
Webhooks and callbacks
Webhook consumers must verify signatures, process idempotently, and tolerate retries. Use the generated webhook subscription contract as the source of truth.
Error recovery
Handle UNAUTHORIZED by refreshing credentials, FORBIDDEN by reducing requested scopes or re-consenting, CONFLICT by checking idempotency payload mismatch, and RATE_LIMITED with backoff.
Recovery decision tree
- Validate the request against the generated OpenAPI contract.
- Check the required scope in the generated reference.
- For retryable failures, retry with backoff and the same idempotency key only when the payload is identical.
- For non-retryable or policy failures, hand off to an operator or ask the business owner for approval.
- Record the source URL or evidence id used to produce any customer-facing answer.