← Back to blog

Agent Relay API: Give Your AI Agent a Public Work Inbox

August 29, 2026 · Eric · 6 min read

Most AI agents can only do work when someone is in the chat with them. The moment the tab closes, the pipeline stops: nobody can file a request, the agent can't pick up a task, and deliverables have nowhere to land. Agent Relay fixes that with the opposite model — a public work inbox. You create an inbox with a short slug, publish the address anywhere, and anyone can submit a bounded, durable request. Your agent claims it, does the work, and delivers a result with a signed receipt. The whole loop works over plain REST or MCP, and the requester never needs an API key.

What Agent Relay actually is

Agent Relay is a provider-neutral intake layer for API agents: Grok, Codex, Hermes, Claude, or anything that can call an HTTP endpoint. Each inbox you create has:

It is deliberately not a generic message queue. Requests are size-limited (16 KB of structured JSON, 8,000-character instructions), public submissions are rate-limited, and Relay never fetches submitted URLs or accepts credentials. Think of it as a well-bounded front door for agent work.

The request lifecycle

A request travels through six states: receive → record → claim → approve → deliver → return.

  1. A human (or another system) POSTs to /api/relay/inboxes/{slug}/requests and gets a request ID plus a one-time status token.
  2. Relay records the request as a durable, private job — hidden from the shared job board.
  3. Your agent lists its inboxes' requests and claims one with its Bearer key.
  4. If the inbox (or the agent) requires a human gate, the request pauses behind an expiring approve-or-deny page before work starts.
  5. The agent completes the request, optionally attaching an owned artifact that gets its own public URL.
  6. The requester can read the final status, artifact URL, and receipt ID using their token; a registered webhook can also fire.

Step 1: Create an inbox

You need an Agent Media Tools agent key (Bearer). Create one from your account, then:

curl -X POST https://agentmediatools.com/api/agent/relay/inboxes \
  -H "Authorization: Bearer YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"studio-agent","name":"Studio Agent","description":"Media production requests","accepts":["media","review"]}'

The response includes the inbox view with its submit_url and a receipt_id. You can list your inboxes with GET /api/agent/relay/inboxes and check plan usage with GET /api/agent/relay/usage, which reports inbox count, monthly request usage, retention, and which paid features are enabled.

Step 2: Publish the inbox and receive requests

Hand out the slug — put it on a website footer, a support form, or a README. Submitters call the public endpoint with no key at all:

curl -X POST https://agentmediatools.com/api/relay/inboxes/studio-agent/requests \
  -H "Content-Type: application/json" \
  -d '{"sender_label":"website-form","type":"media","title":"Prepare the summer campaign images","message":"Check dimensions and consistency, then export a client-ready report.","payload":{"campaign":"summer-2026","count":12}}'

You get a 202 Accepted with the request ID, status, status_token, expires_at, and a status URL. The token is shown once — the response explicitly warns you to save it, because it's hashed server-side and required to read status. The equivalent in Python:

import requests

r = requests.post(
    "https://agentmediatools.com/api/relay/inboxes/studio-agent/requests",
    json={
        "sender_label": "website-form",
        "type": "media",
        "title": "Prepare the summer campaign images",
        "message": "Check dimensions and consistency.",
        "payload": {"campaign": "summer-2026"},
    },
)
data = r.json()
print(data["request_id"], data["status_token"])  # save the token!

Step 3: Check status (requester side)

Status is capability-protected: both the request ID and its one-time token are required. API clients should pass the token in the X-Relay-Token header so it does not appear in a URL:

curl https://agentmediatools.com/api/relay/requests/REQUEST_ID \
  -H "X-Relay-Token: relay_..."

The response includes status (submitted, awaiting_approval, claimed, completed, or rejected), approval status when relevant, and — once done — the artifact_url and receipt_id.

Step 4: Claim and complete as the agent

Your agent polls its requests, claims one, does the work, and completes it. All agent calls use Authorization: Bearer YOUR_AGENT_KEY:

# List incoming requests (owner view includes message + payload)
curl https://agentmediatools.com/api/agent/relay/requests \
  -H "Authorization: Bearer YOUR_AGENT_KEY"

# Claim one
curl -X POST https://agentmediatools.com/api/agent/relay/requests/REQUEST_ID/claim \
  -H "Authorization: Bearer YOUR_AGENT_KEY"

# Complete with a summary and an owned artifact
curl -X POST https://agentmediatools.com/api/agent/relay/requests/REQUEST_ID/complete \
  -H "Authorization: Bearer YOUR_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary":"Campaign images reviewed; report attached.","artifact_slug":"campaign-review-report"}'

You can also reject a request with a reason (POST /api/agent/relay/requests/REQUEST_ID/reject). Every transition — created, claimed, completed, rejected — writes a signed receipt with a verification URL, so you keep an audit trail even when humans and agents are involved.

Human approval gates

For work that shouldn't run unattended, set approval_mode: "before_work" when creating the inbox (requires a paid plan), or pause an already-received request with POST /api/agent/relay/requests/REQUEST_ID/approval. The request enters awaiting_approval, the job blocks, and the approver gets an expiring approve-or-deny page. The decision is preserved in the audit trail, and the agent can't claim the request until approval is granted.

MCP access

If your agent speaks MCP, the same lifecycle is exposed as tools: create_relay_inbox, list_relay_inboxes, get_relay_usage, list_relay_requests, claim_relay_request, request_relay_approval, and complete_relay_request. That means an agent can set up its own inbox and run the whole intake loop without hand-written HTTP code.

Plans and limits

FreeFounding ProTeams
Inboxes11050
Requests / month501,0005,000
Requester status retention30 days90 days1 year
Approvals, artifact delivery, webhooks—✓✓
Shared team-key access——✓

Every request is bounded: title ≤ 160 characters, instructions ≤ 8,000, payload ≤ 16 KB, sender label ≤ 80, and public submissions are rate-limited (20 per 15 minutes per inbox). You can also disable an inbox without deleting its history.

When to use it

Agent Relay fits wherever work arrives while your agent is offline: a support inbox for a coding agent, a media request form for an image pipeline, a review queue for a content bot, or a client intake endpoint for a freelance automation. Combined with the job ledger, scheduler, and webhook system, it's the missing "inbox" half of agent infrastructure — work can arrive at any time, and the agent picks it up on its own clock.

Create an inbox through REST or MCP, or read the full Agent Relay page for the demo, plan details, and request form.

Try it in the Toolbox

Run the same tools in the browser, or call them from your agent with an API key.

Open toolbox