Consumer Documentation

Overview

As a consumer, you can discover and invoke AgentPatch’s context-optimized APIs. Every response includes structured schemas and examples designed for LLM consumption. AgentPatch handles authentication, billing, and request routing.

There are four ways to connect, in order of preference:

1. Skill — recommended for agents that support skills (Claude Code, OpenClaw, and others)
2. CLI — designed for AI agents to use via shell access; works with any agent that can run commands
3. MCP — for agents that support the Model Context Protocol (Claude Code, Cursor, OpenClaw, Codex, etc.)
4. REST API — direct HTTP requests for full control

Skill (Recommended)

A skill teaches your agent how and when to use AgentPatch. Unlike raw MCP, a skill includes prompt context — the agent learns what AgentPatch offers, when to reach for it, and how to use the CLI effectively.

Claude Code

Install the AgentPatch skill:

/plugin marketplace add fullthom/agentpatch-claude-skill
/plugin install agentpatch@agentpatch

OpenClaw

Install the AgentPatch skill from ClawHub:

clawhub install agentpatch

What the skill provides

• Automatic discovery — the agent knows to search AgentPatch when it needs external capabilities (web search, image generation, email, etc.)
• Usage guidance — includes instructions for using the CLI, checking credits, and handling async jobs
• Works with the CLI — the skill teaches the agent to use the ap CLI under the hood, so no MCP config is needed

CLI

Skills use the CLI under the hood, but you can also install it directly for any agent with shell access.

The AgentPatch CLI is designed for AI agents to use via shell access. Install it, and your agent can discover and invoke any tool on the marketplace.

Install (zero dependencies, Python 3.10+):

pip install agentpatch

Set your API key:

export AGENTPATCH_API_KEY=your_api_key

Example commands your agent will use:

ap search "web search"
ap run google-search --input '{"query": "test"}'

Get your API key from the AgentPatch dashboard.

CLI Commands

MCP Interface

AgentPatch provides an MCP (Model Context Protocol) server for AI assistants.

Claude Code

claude mcp add -s user --transport http agentpatch https://agentpatch.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Replace YOUR_API_KEY with your actual key from the AgentPatch dashboard.

OpenClaw

Add AgentPatch to ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "agentpatch": {
        "transport": "streamable-http",
        "url": "https://agentpatch.ai/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_API_KEY"
        }
      }
    }
  }
}

Replace YOUR_API_KEY with your actual key from the AgentPatch dashboard. Restart OpenClaw and it discovers all AgentPatch tools automatically.

Cursor

1. Open Cursor Settings (Cmd+Shift+J on Mac, Ctrl+Shift+J on Windows/Linux).
2. Navigate to the MCP section in the sidebar.
3. Click Add new global MCP server.
4. Cursor opens ~/.cursor/mcp.json. Add the AgentPatch server config:

{
  "mcpServers": {
    "agentpatch": {
      "url": "https://agentpatch.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

5. Replace YOUR_API_KEY with your actual key from the AgentPatch dashboard.
6. Save and restart Cursor. It discovers all AgentPatch tools automatically.

Codex

Add AgentPatch to ~/.codex/config.toml:

[mcp_servers.agentpatch]
url = "https://agentpatch.ai/mcp"
bearer_token_env_var = "AGENTPATCH_API_KEY"

Then set your API key:

export AGENTPATCH_API_KEY=your_api_key

Replace your_api_key with your actual key from the AgentPatch dashboard. Codex discovers all AgentPatch tools automatically on next start.

Generic MCP Client

Connect to one of these endpoints:

• Streamable HTTP: https://agentpatch.ai/mcp
• SSE: https://agentpatch.ai/mcp/sse

Available MCP Tools

• search_tools — Find tools by query
• get_tool_details — Get tool info and schemas
• invoke_tool — Call a tool and get results
• get_job_status — Check job status

Pass your API key via the api_key argument when invoking tools.

REST API

Use the REST API directly if you prefer raw HTTP requests over the CLI or MCP:

# Search for tools (no auth required)
curl "https://agentpatch.ai/api/search?q=email"

# Invoke a tool
curl -X POST "https://agentpatch.ai/api/tools/{slug}" \
  -H "Authorization: Bearer $AGENTPATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "example"}'

# Poll an async job
curl -H "Authorization: Bearer $AGENTPATCH_API_KEY" \
  "https://agentpatch.ai/api/jobs/{job_id}"

Get your API key from the AgentPatch dashboard. See the full OpenAPI spec or Swagger UI for all endpoints.

API Reference

The full API specification is available as an OpenAPI spec (JSON), or you can explore it interactively via the Swagger UI.

Authentication

All API requests require an API key in the Authorization header:

Authorization: Bearer your_api_key_here

Get your API key from the Dashboard after logging in.

Finding Tools

Browse APIs

Visit the Browse page to see available APIs with their descriptions, pricing, and success rates.

List All Tools

GET /api/tools

Returns every active tool with names, descriptions, pricing, input/output schemas, and invocation examples. No authentication required.

Search API

GET /api/search?q=screenshot&max_price_credits=5000&limit=20

Omitting the q parameter returns all tools (equivalent to the list endpoint above, with additional filtering options).

Query parameters:

Get Tool Details

GET /api/tools/{slug}

Returns tool metadata including input/output schemas, pricing, and invocation examples.

Invoking Tools

POST /api/tools/{slug}?timeout_seconds=120
Authorization: Bearer your_api_key
Content-Type: application/json

{
  "url": "https://example.com",
  "format": "png"
}

The request body is the tool input directly, matching the tool’s input_schema. The timeout_seconds query parameter is optional (max 3600).

Synchronous Response (200)

When the tool completes within the timeout:

{
  "job_id": "job_abc123",
  "status": "success",
  "output": { ... },
  "latency_ms": 2100,
  "credits_used": 10,
  "credits_remaining": 9990
}

Async Response (202)

For long-running tasks, you receive a job ID to poll:

{
  "job_id": "job_abc123",
  "status": "pending",
  "poll_url": "/api/jobs/job_abc123",
  "credits_reserved": 10,
  "credits_remaining": 9990
}

Error Response

{
  "job_id": "job_abc123",
  "status": "failed",
  "error": "Tool returned status 400: Invalid URL format",
  "credits_used": 0,
  "credits_remaining": 10000
}

All invocation responses include credits_remaining so your agent can track its budget without extra API calls.

Polling for Results

For async jobs, poll the job endpoint until status changes:

GET /api/jobs/{job_id}
Authorization: Bearer your_api_key

Response:

{
  "job_id": "job_abc123",
  "tool_id": "tl_xyz",
  "status": "success",
  "output": { ... },
  "latency_ms": 45000,
  "credits_used": 10,
  "created_at": "2026-01-28T10:00:00Z",
  "completed_at": "2026-01-28T10:00:45Z"
}

Status Values

Polling Guidelines

• Poll every 10 seconds for quick jobs
• Poll every 30-60 seconds for longer jobs
• Output is available for 24 hours after completion
• Maximum output size is 1 MB

Credits

Credit System

• 1 credit = $0.0001 USD (10,000 credits = $1.00)
• Credits are deducted when you invoke a tool
• Failed invocations (5xx, timeout) are refunded
• Check your balance at GET /api/my/balance

Top-ups

Add credits via Stripe Checkout:

POST /api/my/topup
{
  "amount_credits": 250000
}

This returns a Stripe Checkout URL. Complete payment and credits are added automatically.

Available amounts: $25, $50, $100.

Refund Policy

The 4xx penalty resets after a successful call or 24 hours.