Documentation — AgentBlocks

API Reference

The AgentBlocks API uses REST conventions and returns JSON. All requests require an API key and a version header. Your agent discovers its capabilities by calling GET /agent/info.

Base URL

https://api.agentblocks.ai

Authentication

All API requests require a Bearer token and the X-Agent-Version header.

Required headers

Authorization: Bearer sk_your_api_key

X-Agent-Version: 2026-02-23.02

API keys start with sk_ and are created per-agent in the dashboard. If the X-Agent-Version header is missing or outdated, the server returns 426 with a link to re-fetch the agent guide.

Discovery

Your agent should always start by calling this endpoint to learn what it can do.

GET/agent/info

Discover your agent's capabilities, email addresses, and links to capability-specific guides.

Response

{

"agentSlug": "research",

"accountSlug": "acme",

"defaultAddress": "[email protected]",

"capabilities": ["email", "github", "gmail", "drive", "slack"],

"guides": {

"email": "https://api.agentblocks.ai/agent-guide/email",

"github": "https://api.agentblocks.ai/agent-guide/github"

}

The agent should fetch each URL in guides to learn the full API for that capability. Do not hardcode capabilities — always discover them from this endpoint.

Polling for Status

When an action requires approval, poll this endpoint for a resolution.

GET/operations/:token

Check the status of a pending operation. Poll with exponential backoff (every 5–30 seconds) until a terminal status is reached.

type	Meaning	Terminal?
queued	Awaiting human approval	No
approved	Approved and executed	Yes
rejected	Human rejected the request	Yes
timed_out	Expired before approval	Yes
failed	Approved but execution failed	Yes

Email

Give your agent a dedicated @agentmx.io email address to send and receive real emails.

POST/email/send-request

Request to send an email. Requires human approval unless auto-allowed by policy. Returns an LRO envelope.

Fields: to (required), subject (required), body (required, plain text), from (optional prefix). Supports Idempotency-Key header.

GET/email/inbound

Fetch inbound emails. Query params: limit (1–100), before (cursor for pagination). Ordered newest-first.

GET/email/inbound/:id

Get a single inbound email by ID.

Rate limits: 10 sends/hour, 50 sends/day per agent. Inbound attachments are dropped — only text content is stored.

GitHub

Push, pull, and fetch with short-lived GitHub tokens. All git operations go through the agentblocks-git wrapper script.

Important: Your agent does not have direct push access. All authenticated git operations use the agentblocks-git script, which handles token requests, approval polling, and automatic token revocation.

Setup

# Download into .git/ (keeps it out of the working tree)

curl -sf https://api.agentblocks.ai/agentblocks-git -o .git/agentblocks-git

chmod +x .git/agentblocks-git

Usage

# Push using the wrapper instead of plain git push

AGENTBLOCKS_API_KEY=sk_your_key .git/agentblocks-git push origin main

# Fetch works the same way

AGENTBLOCKS_API_KEY=sk_your_key .git/agentblocks-git fetch

The script waits for approval if needed, then executes the git operation with a scoped token. The token is revoked immediately after use. If the script is interrupted, use --resume <token> to pick up where it left off.

Gmail

Read, reply, forward, and compose emails from a linked Gmail account. Actions execute on AgentBlocks servers.

GET/gmail/inbox

List inbox messages. Optional query params: q (Gmail search query), maxResults.

GET/gmail/messages/:id

Get a specific message by ID with full content.

POST/gmail/reply

Reply to a message (threaded). Fields: messageId, body. Requires approval.

POST/gmail/forward

Forward a message. Fields: messageId, to, body (optional). Requires approval.

POST/gmail/send

Compose a new email. Fields: to, subject, body. Requires approval.

POST/gmail/messages/:id/archive

Archive a message (removes INBOX label).

POST/gmail/messages/:id/labels

Add or remove labels. Fields: addLabelIds, removeLabelIds.

GET/gmail/labels

List all available labels for the connected account.

Rate limits: 200 reads/hour, 20 sends/hour per agent. All send/reply/forward endpoints support Idempotency-Key headers.

Google Drive

List files, read metadata, and read file content from a linked Google Drive. Content reads require approval by default.

GET/drive/files

List files. Optional params: q (Drive search query), maxResults, pageToken.

GET/drive/files/:id/metadata

Read a file's metadata (name, owner, dates, labels).

GET/drive/files/:id/content

Read a file's content. Requires approval by default. Google Docs/Sheets/Slides are auto-exported to text formats. Optional param: mimeType.

Slack

Read channels, search messages, and post to a connected Slack workspace.

GET/slack/channels

List channels (public, private, DMs, group DMs) the user is in.

GET/slack/users

List workspace members. Slack Connect (external) users are not included.

GET/slack/users/:userId

Look up any user by Slack user ID, including external Slack Connect users.

GET/slack/search?q=...

Search messages across the workspace. Requires approval. Params: q, page, count.

GET/slack/channels/:channelId/messages

Read recent messages in a channel or DM. Param: limit.

POST/slack/channels/:channelId/messages

Post a message as the user. Requires approval. Body: { text }.

POST/slack/channels/:channelId/reply

Reply in a thread. Requires approval. Body: { text, threadTs }.

Error Codes

Standard HTTP error codes used across all endpoints.

Status	Meaning
400	Missing or invalid fields
401	Missing, malformed, or invalid API key
403	Access denied or scope upgrade required
404	Resource not found
409	Idempotency key reused with different payload
426	Missing or outdated X-Agent-Version header
429	Rate limit exceeded