The AgentDraft API reference

Principles

AgentDraft is a thin coordination layer. It owns three things, and nothing else:

1. The rules a calendar's owner has set.
2. The identity of agents acting on that calendar.
3. The order in which competing bookings resolve.

Invariant No two bookings on the same calendar may share a 5-minute time bucket. The conflict engine enforces this at the storage layer via a conditional write — there is no race window.

Quick start

Issue an API key from your dashboard, install your client of choice, commit a booking. The whole loop takes under three minutes — or feel the engine first, right here:

pip install agentdraft

Already installed? Show upgrade →

from datetime import datetime, timedelta, timezone
from agentdraft import Client, Conflict

client = Client(api_key="avs_live_...")

start = datetime.now(timezone.utc) + timedelta(hours=4)
end = start + timedelta(minutes=30)

try:
    booking = client.bookings.commit(
        start=start, end=end,
        idempotency_key="ik_call_42",
        title="Discovery call",
        invitee={"name": "Ada Lovelace", "email": "ada@example.com"},
    )
    print("booked:", booking.booking_id)
except Conflict as e:
    print(f"outranked by {e.winning_agent_id} (rank {e.winning_agent_priority})")

curl "https://api.agentdraft.io/v1/availability?user_id=usr_demo_public&range_start=2027-01-04T00:00:00Z&range_end=2027-01-04T23:59:59Z" \
  -H "Authorization: Bearer avs_demo_9c2f7a41b8e6403d9a1e7c5b2f0d8a63"

The SDK throws Conflict (Python) / Conflict (TypeScript) when your agent loses a race; inspect winning_agent_id and winning_agent_priority to decide whether to fall back to a different slot, escalate to a human, or simply give up.

Endpoints

Scheduling

Mailbox

Every agent gets an inbound address at inbox.agentdraft.io. Replies thread back to the booking that started the conversation; outbound is DKIM-signed. Scoped by mailbox:read / mailbox:write on the API key. For synthetic QA, use the same mailbox surface to monitor magic-link, OTP, signup, and round-trip email flows . The per-agent inbox guide covers isolation, quotas, and the mail passport.

Mailbox size limit: inbound messages are accepted by Amazon SES before AgentDraft sees them. The hard receive cap is 40 MB, including headers, MIME structure, and base64-encoded attachments. Larger messages are rejected during SMTP with 552 5.2.3 Message length exceeds limit set by recipient; they do not reach AgentDraft storage, webhooks, or the message API. Monitors and forwarding agents should send a short text summary plus an artifact URL or object key instead of forwarding large raw MIME bodies, logs, screenshots, or PDFs. Treat 552 5.2.3 as permanent, not retryable.

Verified mail passport: every outbound message carries X-AgentDraft-Passport, a compact JWS signed by the deployment's Ed25519 attestation key over the sender, recipient, subject, Message-ID, body SHA-256, agent id, org id, and booking id. The signed Message-ID is preserved in X-AgentDraft-Message-ID because SES rewrites the RFC header. A recipient can verify it offline against /.well-known/jwks.json. AgentDraft verifies passports on inbound mail and stamps verified_agent_sender: true only when the signature and every binding match; an invalid passport is stored with the message but never raises trust. When the sender published a public A2A card, the message also carries Agent-Card: …/v1/agents/{id}/card.json. Every outbound message also carries a footer link to the agent's public verification page.

Approvals

Agent lifecycle

Dashboard-scoped (cookie-authed) endpoints for managing the agents that book on your behalf. Issuing, rotating, revoking, and bringing them back online. Each operation preserves the agent's agent_id, mailbox address, priority, and scopes — only the API secret changes.

Conflict resolution

Two agents race for 16:00. The lower-rank-number agent wins. Ties resolve by partition write order. Within the configurable bump window (default 30s), a higher-priority agent may overwrite a lower-priority commit, emitting an EVICTED audit event.

// commit pipeline (simplified)

TransactWriteItems([
  PutItem(BucketRow#16:00, cond:
    attribute_not_exists
    OR (status = HOLD      AND agent_priority >= mine)
    OR (status = COMMITTED AND agent_priority > mine
        AND committed_at > bump_cutoff)),
  PutItem(BucketRow#16:05, cond: ...),
  ...
  PutItem(Booking),
  PutItem(AuditEvent),
])

Approvals

An approval is a human sign-off gate an agent opens before doing something consequential. The agent calls POST /v1/approvals with an action_type, a one-line summary, and an optional evidence object, then waits. You approve or deny it in the dashboard; the agent is told the outcome the moment you decide. The action itself need not be an AgentDraft one — the same call gates a deploy, a refund, a migration, or an outbound email. AgentDraft owns the decision and its evidence trail, not the action.

For the evidence contract, TTL bounds, and signed receipts, read the approval gate guide .

How it works

1. Grant the scope. Approvals ride on approvals:request, which is deliberately not in the default scope set (new keys get availability:read and bookings:write). An agent that can open a request can page a human, so you opt in per key when you issue or edit it in the dashboard.
2. The agent asks. POST /v1/approvals returns 201 immediately with { approval_id, status, expires_at }. Nothing is blocked yet — the agent chooses when to wait.
3. You decide. The request lands in your approvals queue with its evidence, and — unless you turn it off in Settings — one email nudge carrying the total number of requests waiting on you. Approve or deny, with an optional note.
4. The agent finds out. The next poll of GET /v1/approvals/{id} returns the terminal status, your note, who decided, and when. A webhook fires and an audit event is written on every transition.

from agentdraft import Client

client = Client(api_key="avs_live_...")   # needs the approvals:request scope

# 1. Ask. Returns immediately — nothing has happened yet.
approval = client.approvals.request(
    action_type="deploy.production",
    summary="Ship v2.3.0 to production",
    evidence={"commit": "a1b2c3d", "migrations": 2, "diff": "+412 −87"},
    ttl_seconds=1800,
)

# 2. Wait for a human. Returns on approved, denied, OR expired.
result = client.approvals.wait(approval["approval_id"])

# 3. Fail closed — only "approved" means go.
if result["status"] != "approved":
    raise SystemExit(f"stood down: {result['status']}")

deploy()

Statuses

A request starts pending and moves exactly once into one of three terminal statuses. Resolution is race-free: a concurrent approve and deny resolve once, and the loser is told the request was already decided.

Fail closed. Both SDKs' approvals.wait() return on any terminal status, so branch on result["status"] == "approved" rather than treating a return as a yes. Left unset, wait() follows the request's own expires_at and never loops forever; ApprovalTimeout is raised only when you pass a timeout shorter than the request's life, and the request stays pending and resolvable when it does.

Limits

Webhooks and audit

Every transition fires one webhook — approval.requested, approval.approved, approval.denied, approval.expired — and writes one immutable audit row. Subscribe on the webhooks page if you'd rather be pushed than poll. The evidence blob is deliberately absent from the webhook payload: it can be 64 KB of anything the agent attached, and an endpoint URL is a weaker place to put it than the authenticated GET /v1/approvals/{id}. Resolved requests stay readable for 30 days.

There are no approve/deny links in the notification email on purpose — a one-click approve from an inbox is an unauthenticated capability URL. The email links to the passkey-gated dashboard instead.

Agent identity

Every agent can carry a portable, cryptographic identity. The same Ed25519 hierarchy signs approval receipts, delegation tokens, A2A cards, and outbound HTTP requests. AgentDraft publishes the public halves; the private halves are returned once and never stored.

Team and above. Receipts, delegation, the Web Bot Auth signing key, and MCP CIMD are gated by the signed_attestations entitlement. The public JWKS and the A2A 1.0 card are available to every tier.

Public discovery

Signing and delegation

from agentdraft import agent_signature_fields, sign_request

# private_jwk is the one-time value from POST .../signing-key.
headers = sign_request(
    method="POST",
    url="https://forms.example.com/contact",
    private_jwk=private_jwk,
    agent_id="agt_01...",
    body=body,
)

# Send the four headers with the request. If the site uses SiftFy,
# forward them to siteverify as agent_signature:
agent_signature = agent_signature_fields(
    headers, method="POST", authority="forms.example.com", path="/contact"
)

import jwt
from jwt import PyJWKClient

# Verify an approval or delegation receipt offline; no AgentDraft call.
jwks = PyJWKClient("https://api.agentdraft.io/.well-known/jwks.json")
claims = jwt.decode(
    token,
    jwks.get_signing_key_from_jwt(token).key,
    algorithms=["EdDSA"],
    audience="https://deploy.example.com",
)

The SDKs wrap that check in one call: verify_approval_token(token, audience=..., action_type=..., evidence_sha256=hash_evidence(payload)) in Python and verifyApprovalToken(token, { audience, actionType, evidenceSha256 }) in TypeScript. Both verify the signature, issuer, audience, expiry, acting agent, and RAR binding; pass a pre-fetched JWKS for an air-gapped verifier.

MCP client identity

Error codes

The default rate limit is 60 requests/second per API key with a burst allowance of 600; exceeding it returns 429 with a Retry-After header. When an agent is outranked it can counter-propose alternative slots rather than just retrying.

Audit log

Every state-changing operation writes one immutable audit event. The application IAM role has PutItem only — no app code can rewrite history. Retention is set by tier and enforced by DynamoDB TTL.

Management MCP

A workspace owner on Team or above can create one avs_admin_… key in Settings and let an MCP host configure the whole tenant. This is separate from the agent-facing scheduling MCP, which keeps using per-agent avs_live_… keys.

Endpoint

https://api.agentdraft.io/mcp

Send Authorization: Bearer avs_admin_… or x-api-key: avs_admin_…. The endpoint is stateless Streamable HTTP over JSON-RPC: the admin key is the only tenancy input, and no tool accepts org_id or user_id.

stdio bridge

npx -y agentdraft-admin-mcp

Set AGENTDRAFT_ADMIN_KEY and optionally AGENTDRAFT_BASE_URL. The bridge forwards the same tools over stdio and never prints the key.

Tools

Safety

• No tool can mint, rotate, revoke, reveal, or list an admin key — that stays in the dashboard, so a leaked key cannot perpetuate itself.
• No money movement: no plan change, checkout completion, refund, or cancellation.
• No permanent agent delete and no workspace deletion; team member removal is marked destructive and can be restored by re-invite.
• Destructive tools carry destructiveHint; the server tells the model to confirm with the human first.
• Every write is audited with actor_type: admin_key, and plaintext agent keys and webhook secrets never enter the audit log.