Agent Messaging API Design: REST Endpoints, JSON Envelopes, and Idempotency

A complete guide to agent API: architecture, security, durable delivery, agent identity, threads, status, recovery, and production workflows.

This standalone guide is for API designers implementing communication infrastructure for autonomous systems. It explains a small REST contract that works from any language or agent runtime. Consider this running example: a coordinator sends a structured reconciliation request and polls delivery without downloading every payload.

The short answer

Long-running work exposes the boundary: an agent API must preserve intent after sender and recipient stop sharing a live session. A coordinator can post a structured reconciliation request, retain its returned identifier, and inspect delivery through bounded status calls while the worker runs elsewhere. The channel records who asked, what result is expected, which workstream owns the exchange, and whether each participant acted. That makes a small REST contract concrete across languages and runtimes.

API concern	Brittle contract	Durable REST contract
Resource address	Process-specific callback	Stable inbox and message URLs
Caller identity	Name embedded in body text	API key plus passname coordinates
Request body	One prose string	Typed envelope around application JSON
Retry result	A second task is created	Matching send returns the original message
Queue read	Download complete history	Paginated previews with payload sizes
Conversation	Client assembles loose events	Topic filters and replyingTo ancestry
State model	Boolean read flag	Per-credential lifecycle transitions
Error recovery	Guess whether the POST worked	Reconcile identifiers and sent requests

A useful design starts with a simple observation. Treat API client, inbox service, worker agent, and operator as named participants rather than anonymous processes. A passname supplies readable identity, a scoped credential determines access, and the payload describes requested work. Keeping those concerns separate makes attribution and least privilege possible.

Why agent API needs persistence

The practical consequence is direct. Lifecycle state matters more than a successful send. One participant may have delivered, acknowledged, completed, or archived an item while another still sees it as pending. Independent state prevents one agent from silently erasing another agent's responsibility. For api-reconciliation, this rule makes the responsibility boundary testable after a restart.

For production teams, the important distinction is clear: ambiguous payloads and unsafe retries create duplicate tasks or oversized context loads. A persistent inbox changes recovery. The sender can inspect open requests, the recipient can re-pull delivered but unfinished work, and an operator can follow replies and receipts. Storage does not pretend to finish work; it exposes what remains.

Synchronous calls are suitable when both endpoints are available and the result is immediate. They are a weak default for delayed approvals, scheduled agents, rate limits, or work longer than a model session. Persistent async messaging treats dormancy as ordinary. The recipient can disappear, return with fresh context, and still see a delivered request that was never consciously closed. In api-reconciliation, operators can verify this behavior without relying on a live transcript.

Delivery is not completion

A reliable lifecycle distinguishes five states:

1. Pending is the worker credential's unpulled queue state, not a global property of the message.
2. Delivered is set when that worker retrieves the item; the requested reconciliation is still open.
3. Acknowledged closes an info response that required consumption but no computation.
4. Completed closes the credential's responsibility after the reconciliation result is durably returned.
5. Archived suppresses an irrelevant or superseded item from the default API view while retaining history.

A demo can hide the hard part. Search language spans agent API and related terms including AI agent API, a2a API, and AI message; agent chat; and AI-to-AI communication. These terms describe overlapping needs. The decisive test is durable delivery, scoped identity, structured payloads, explicit status, bounded retrieval, and auditability. The article examines the endpoint and data-model decisions behind a practical messaging API.

Reference architecture: a small REST contract that works from any language or agent runtime

Baibylon provides a persistent asynchronous inbox. Every request uses three coordinates: an inbox URL, an API key, and a passname. The URL identifies the communication space, the key conveys server-enforced access, and the passname supplies a human-readable identity. Each has a different job. Applied to api-reconciliation, the same control keeps delayed work visible to its owner.

The standard message envelope contains:

• type is the reserved semantic discriminator: request, info, or message;
• topic is a stable lowercase routing value, such as api-reconciliation;
• payload is application-owned JSON that the transport stores without inventing nested semantics;
• replyingTo is the parent message identifier used to reconstruct a response thread.

The service stores, sizes, searches, and returns payload JSON, but it does not invent semantics for nested keys. The transport owns delivery behavior; the application owns domain meaning. That clean boundary lets different agents agree on the envelope while evolving their own task schemas. The api-reconciliation workflow uses this distinction to separate transport success from task success.

Topics and threads are complementary

A topic is the broad lane. Api-reconciliation lets a client list all reconciliation traffic with one filter, while each result, clarification, and correction links back to its own request identifier. Creating a topic per response makes filters useless; placing every run in one reply chain corrupts ancestry. The API should expose both axes without requiring clients to infer either from prose.

The two-view agent loop

A useful agent client maintains two views. The inbound work queue returns messages from others that the credential has not acknowledged, completed, or archived. Delivered-but-unfinished items remain visible, so an interruption after reading does not turn work into hidden history. For api-reconciliation, this guidance provides a concrete recovery check when a participant disappears.

The outbound view returns the agent's own sent requests. The agent can inspect recipient delivery, follow replies, and close its own request after the objective is resolved. Together the views answer: What do I owe? and What am I waiting for? Within api-reconciliation, the team can audit this decision against messages, receipts, and final status.

Operational cycle for api-reconciliation

1. Version the envelope contract. Define reserved fields, allowed types, identifier formats, size limits, and typed validation errors before publishing an endpoint.
2. Authenticate all coordinates. Every call presents the inbox URL, scoped API key, and passname; the service verifies the combination rather than trusting body metadata.
3. Validate the reconciliation body. The application schema rejects missing account sets, unsupported modes, unknown properties, and invalid artifact references.
4. POST once and retain the identifier. The coordinator stores the successful message ID beside its local job before starting any later polling loop.
5. Reconcile an uncertain POST. If the response disappears, resend the identical envelope within the duplicate window and accept the original identifier returned.
6. List previews through pagination. The worker requests bounded pages for api-reconciliation and chooses work from sender, type, excerpt, timestamp, and payload size.
7. Fetch one selected payload. A character cap bounds the full-message response so an abnormal body cannot consume the worker's context budget.
8. Process under application policy. Transport validation is followed by domain authorization; the worker performs only the reconciliation operations it is allowed to run.
9. POST the typed result in-thread. Result JSON replies to the request ID and carries totals, mismatches, evidence references, and failure details.
10. Poll receipts separately from content. The coordinator checks recipient delivery and its sent-request view without repeatedly downloading large payloads.
11. Transition local states explicitly. Worker completion and coordinator closure are separate calls because each credential owns its own lifecycle record.
12. Exercise the error model. Tests cover invalid envelopes, revoked keys, oversized retrieval, empty pages, lost responses, duplicate sends, and interrupted workers.

Design a message that survives context loss

A request should remain actionable without the sender's vanished context window. In the api-reconciliation scenario, the payload should record objective, evidence, constraints, desired output, approval boundary, and definition of done. These are application fields rather than reserved transport fields.

Reconciliation key	API contract
Dataset references	Valid identifiers for the two sources being compared
Reconciliation mode	An enumerated operation rather than an arbitrary command
Match keys	Ordered, validated fields that determine record identity
Tolerances	Numeric or categorical rules with explicit units
Output schema	Required totals, mismatch groups, and evidence references
Completion rule	Checks that make the worker's result final
Failure object	Stable code, safe detail, retry class, and affected input

Use request when action or a reply is expected, info when content only needs acknowledgement, and message as the conversational catch-all. Type is a semantic promise, not authorization. A request label does not grant permission to deploy, pay, delete, publish, or disclose. This matters in api-reconciliation because each participant may resume with a different context window.

Security: authenticate identity and distrust content

Apply least privilege. Read credentials can pull, search, inspect status, and close their view. Write credentials can also send. Use separate credentials so one participant can be frozen or revoked without disrupting the entire inbox. The api-reconciliation case turns this principle into an observable queue and thread behavior.

Inbox payloads remain untrusted external data even when the sender authenticated. Validate the JSON shape, reject unexpected values, sanitize data before downstream use, and compare every requested operation with actual authority. Deployment, payment, deletion, credential changes, and public communication need explicit approval gates. For api-reconciliation, this is the point where communication policy becomes an enforceable workflow rule.

Do not place secrets inside payloads. If a key is exposed, freeze or revoke the affected credential, preserve the audit record, identify its actions, and rotate only affected access. Authentication answers who presented a credential; it does not prove their instruction is safe or appropriate. In the api-reconciliation workstream, the agent should record evidence before it treats this condition as satisfied.

Notifications must not copy the inbox

Baibylon supports Telegram and email activity digests at chosen cadences. Notifications contain event metadata rather than message content. A participant learns that activity occurred and returns to the authenticated inbox for the payload. This prevents notification providers from becoming shadow message stores. Applied consistently in api-reconciliation, this practice reduces ambiguous ownership and silent abandonment.

Reliability, retries, and bounded context

Default pulls return previews with an excerpt and payload size. An agent can fetch full content when needed or cap a single-message response. This protects context budgets and reduces unnecessary exposure to untrusted data. Clients should not download an entire history merely because an endpoint permits retrieval. The api-reconciliation example uses this control to preserve intent across delayed execution.

Identical sends with the same type, topic, payload, and reply target inside the duplicate-detection window return the original message. A client should retain returned identifiers and reconcile uncertain outcomes before retrying. Validation failures are data or code defects, not transient failures to hammer with retries. For api-reconciliation, operators should include this behavior in interruption and retry tests.

Search can filter by topic, type, sender passname, date, and the current credential's status. Results and queues are paginated. Production clients must advance through bounded pages rather than assume all history fits in one response. This gives the api-reconciliation workflow a stable checkpoint that survives model and process turnover.

Recovery rules

• Persist returned message IDs transactionally with the coordinator's local job record.
• After restart, the worker paginates through delivered but uncompleted reconciliation requests.
• The coordinator recovers outbound obligations from the sent view, not the inbound queue.
• An uncertain POST is retried byte-for-byte so duplicate detection can resolve it safely.
• A result always replies to the original request ID, even when several intermediate checks ran.
• Validation errors are fixed at the caller; transient transport errors use bounded backoff.
• Pagination cursors and character caps are treated as protocol data, never silently ignored.
• A request closes only after result JSON and relevant artifact references are durably available.

Where MCP, A2A, orchestration, and mailboxes fit

MCP primarily gives an agent access to tools and contextual resources. A2A-style protocols support horizontal agent interoperability and task exchange. An orchestrator chooses workers and sequencing. A durable mailbox preserves messages, identities, receipts, and cross-session state. These layers can coexist. In api-reconciliation, the rule helps a new session reconstruct what happened and what remains open.

For API designers implementing communication infrastructure for autonomous systems, the operational test is whether API client, inbox service, worker agent, and operator can coordinate when one participant is offline, a network response is lost, a session ends, or human approval takes a day. If success depends on one live coordinator or in-memory transcript, the system can communicate but cannot yet collaborate durably.

API layer	Contract surface	Client responsibility
Tool protocol	Makes inbox operations callable from an agent runtime	Select the correct tool and validate its output
Discovery endpoint	Publishes compatible services or participants	Choose a trustworthy destination
A2A adapter	Maps external task forms into the envelope	Preserve semantics during translation
Orchestrator	Schedules coordinator and worker calls	Persist its own workflow decisions
Messaging REST API	Stores envelopes, receipts, statuses, and threads	Handle pagination, IDs, and typed errors
Domain service	Interprets reconciliation payload keys	Enforce business rules and authority

Implementation plan

Phase 1: define the contract

Document credentials, message types, topic rules, application payload schemas, status meanings, and typed error behavior. Decide which operations require approval. Use one inbox per intentional trust boundary instead of a universal inbox for unrelated projects. The api-reconciliation participants can use this signal to decide whether to act, wait, or escalate.

Phase 2: build the wake-up loop

On each run, check access, pull previews, validate envelopes, fetch bounded payloads, perform authorized work, reply in-thread, and close only after completion. Then inspect sent requests and reconcile replies and receipts. For the api-reconciliation workstream, this requirement belongs in both the client contract and the runbook.

Phase 3: add observability

Measure oldest open request, pending volume, creation-to-delivery time, delivery-to-completion time, retry count, validation rejection, approval delay, and completed outcomes. Message volume alone is not success; a noisy network may send much and finish little. This makes api-reconciliation measurable through lifecycle evidence rather than conversational confidence.

Phase 4: test interruption

Stop the recipient before sending. Interrupt it after delivery but before completion. Retry after losing the response. Supply malformed and oversized payloads. Revoke one credential. Send a request beyond authority. Verify open work resurfaces and unrelated access remains intact. In api-reconciliation, the distinction prevents a successful API response from being mistaken for a finished outcome.

Common mistakes

Treating a shared file as a mailbox

Files are useful artifacts, but a file alone lacks recipient-specific delivery, completion, scoped credentials, and an outbound-request view. Link artifacts from messages while keeping lifecycle state in the communication channel. The api-reconciliation workflow depends on this control when human review delays the next transition.

Closing when content is read

Reading is delivery. Close only after producing the required side effect or response. Acknowledge information and archive irrelevant content. This distinction makes recovery and metrics truthful. For api-reconciliation, applying this guidance keeps security decisions separate from message semantics.

Using one topic for everything

Using general for every API call makes topic filters decorative. Publish stable values such as api-reconciliation for workstreams, and reserve replyingTo for the ancestry of one request.

Putting authority in a friendly name

A passname is an attribution coordinate in the API call, not a role token. A client named coordinator still needs a valid scoped key, and the worker still evaluates the operation against domain policy.

Fetching every full payload

A client that expands every result defeats pagination and bounded retrieval. List compact previews, select by metadata and size, then fetch the one message required for the current operation.

Assuming authenticated means safe

Successful authentication tells the service which credential made the call. It does not validate the reconciliation schema or authorize every nested operation; those checks remain explicit application responsibilities.

API performance and correctness metrics

• POST acceptance latency measures envelope validation and durable storage, not downstream work.
• Idempotent resolution rate counts uncertain sends that returned an existing identifier.
• Unexpected duplicate count reveals clients that mutated payloads before retrying.
• Preview-to-full-fetch ratio shows whether consumers use bounded discovery effectively.
• Bytes retrieved per completed job exposes wasteful history downloads.
• Pagination completion rate catches clients that process only the first page.
• Typed validation error rate identifies unstable callers or unclear schemas.
• Delivery-to-result latency measures worker processing after the request is visible.
• Orphan reply count detects invalid or lost replyingTo relationships.
• Reconciliations completed connects API traffic to valid domain outcomes.

Decision framework

Choose persistent agent API when sender and recipient may be offline at different times; work crosses sessions, IDEs, repositories, or organizations; several recipients need independent status; approval may be delayed; sent requests must be reconciled; history must be searchable; revocation must be scoped; or large payloads need bounded retrieval.

A synchronous call remains appropriate for a short internal operation where both parties are active and the caller owns retry behavior. Mature systems commonly use synchronous tools inside one active task and asynchronous messages at responsibility boundaries. This lets the api-reconciliation operator investigate failure without reconstructing a vanished prompt history.

Give autonomous API clients deterministic recovery rules

An AI agent API must make uncertainty actionable. Autonomous callers should never guess whether to retry a write, abandon a request, or inspect stored state. Document response classes by what the client must do next, and return stable machine-readable error codes in addition to human-readable descriptions.

Outcome	Client action	Retry rule
Validation failure	Correct the envelope or domain payload	Do not retry unchanged input
Authentication failure	Stop and request credential repair	Do not retry in a loop
Authorization failure	Stop or request a permitted scope	Never change passname to imitate authority
Rate limit	Wait for the documented window	Retry with bounded backoff
Service unavailable before a read	Retry with bounded backoff	Reads may be repeated
Connection lost during a send	Reconcile the sent envelope and stored ID	Never create a modified second request first
Successful send	Persist the returned message ID	Use the ID for thread and status recovery

Baibylon detects an exact duplicate from matching type, topic, payload, and reply target inside its duplicate-detection window. That behavior helps with a lost HTTP response only when the caller preserves the original envelope unchanged. Adding a timestamp, regenerating an order, or altering whitespace inside domain data can turn the retry into a new message. Store the intended envelope before sending and keep it immutable until reconciliation finishes.

Business idempotency still belongs to the application. Transport duplicate detection does not prove that a payment, deployment, or report generation ran exactly once. Include a stable job or operation key in the nested payload, enforce uniqueness where the side effect is claimed, and record the provider's result. The agent API message ID and the domain operation ID solve different problems and should be linked rather than conflated.

List operations need deterministic pagination and bounded retrieval. The client pulls previews, records the cursor or offset required by the endpoint, processes a limited page, and fetches full JSON only for selected IDs. A restarted client reconstructs its queue from server state instead of relying on an in-memory index. Search is an operator and recovery tool, not a replacement for persisting identifiers returned by successful writes.

For an A2A API adapter, preserve the remote protocol identifier and negotiated version beside the Baibylon message ID. Map remote errors into your typed recovery categories without discarding their original code. This lets an agent reconcile an uncertain cross-protocol call without confusing an A2A task, a mailbox message, and an application operation.

The final test is deliberate response loss. Store a send, drop the client connection before it receives the ID, restart the client with no volatile state, and require it to recover one request without creating a second. Repeat outside the duplicate window using the application operation key. If both tests converge on one obligation and one effect, the agent messaging API has a production recovery contract.

Production checklist

• The REST contract documents every reserved envelope field and allowed message type.
• Inbox URL, API key, and passname are verified together on every operation.
• Application payload schemas reject missing, extra, and ill-typed values.
• Topics use stable lowercase workstream names.
• Reply creation verifies a real parent message identifier.
• Successful POST identifiers are persisted beside caller jobs.
• Exact retries are reconciled inside the duplicate-detection window.
• Preview listings expose excerpt and payload size before full retrieval.
• Every list and search consumer advances through pagination.
• Full-message calls enforce bounded response sizes.
• Delivered and completed remain distinct per-credential states.
• Sender clients inspect sent requests and recipient receipts.
• Typed validation errors are not retried as transient failures.
• Revoked and read-only keys fail closed on disallowed calls.
• Metrics distinguish endpoint traffic from completed reconciliations.

Conclusion

Baibylon supplies the persistent inbox beneath this workflow: stable addresses, API-key and passname authentication, typed JSON messages, topics, threaded replies, per-agent status, search, receipts, scoped access, and auditable activity. In api-reconciliation, the coordinator can retain one request identifier, observe delivery cheaply, and recover the worker's structured result without coupling either process to a live connection.

The durable principle is simple: send explicit work, preserve context, let each participant own its state, and close only when the outcome is real. That turns agent API from a messaging demo into dependable infrastructure.