Provider Documentation

Overview

As a provider, you build and host a tool endpoint that AgentPatch will invoke on behalf of customers. You set your own pricing, and the platform handles discovery, billing, and request routing.

API Reference

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

HTTP Interface

Your endpoint receives POST requests with the following headers:

The request body contains the input matching your tool’s input_schema.

Response Codes

200 — Synchronous Result

Return this when your tool can respond immediately (within 60 seconds).

{
  "result": "Your output here",
  "data": { ... }
}

The response body should match your tool’s output_schema.

202 — Async Job

Return this for long-running tasks. You must later POST the result to the callback URL.

{
  "estimated_seconds": 120
}

The estimated_seconds field is optional and helps callers set polling intervals.

4xx/5xx — Errors

• 4xx errors: Indicate bad input from the caller. Credits may be partially refunded.
• 5xx errors: Indicate a problem with your tool. Credits are fully refunded to the caller.

Async Callbacks

For async jobs (202 response), POST results to the callback URL provided in X-AgentPatch-Callback:

POST {callback_url}
X-AgentPatch-Callback-Token: {token from header}
Content-Type: application/json

{
  "status": "success",
  "output": { ... }
}

For failures:

{
  "status": "failed",
  "error": "Description of what went wrong"
}

Callbacks must arrive within your tool’s max_timeout (up to 1 hour). Jobs that exceed the timeout are marked failed and credits are refunded.

Verifying Request Signatures

If you configure an endpoint_secret in your tool settings, AgentPatch signs all requests. This lets you verify requests came from AgentPatch rather than someone calling your endpoint directly.

The signature is an HMAC-SHA256 of {timestamp}.{body} using your secret.

Verification Steps

1. Get the timestamp from X-AgentPatch-Timestamp
2. Get the signature from X-AgentPatch-Signature
3. Compute HMAC-SHA256 of {timestamp}.{raw_body} with your secret
4. Compare signatures using a timing-safe comparison
5. Reject if timestamp is older than 5 minutes (prevents replay attacks)

Node.js Example

import { createHmac, timingSafeEqual } from "crypto";

function verifySignature(
  body: string,
  timestamp: string,
  signature: string,
  secret: string
): boolean {
  const now = Math.floor(Date.now() / 1000);
  const ts = parseInt(timestamp, 10);
  if (Math.abs(now - ts) > 300) {
    return false;
  }

  const payload = `${timestamp}.${body}`;
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  if (expected.length !== signature.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Python Example

import hmac
import hashlib
import time

def verify_signature(body: str, timestamp: str, signature: str, secret: str) -> bool:
    now = int(time.time())
    ts = int(timestamp)
    if abs(now - ts) > 300:
        return False

    payload = f"{timestamp}.{body}"
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

Caller Identification

The X-AgentPatch-Caller-Id header contains the UUID of the customer making the request. Use this for:

• Rate limiting: Limit requests per caller to prevent abuse
• Session state: Track conversation context across multiple calls
• Usage analytics: Understand how different callers use your tool

Listing Your Tool

When creating a tool in the dashboard, provide:

• Name: Display name for your tool
• Slug: URL-friendly identifier (e.g., my-tool)
• Description: What your tool does
• Endpoint URL: Where AgentPatch sends requests
• Endpoint Secret: (Optional) For request signature verification
• Input Schema: JSON Schema describing expected input
• Output Schema: JSON Schema describing your output format
• Price: Cost per call in credits (1 credit = $0.0001, i.e., 10,000 credits = $1.00)
• Timeouts: Default and maximum timeout values

Testing Your Tool

Test your tool through the dashboard before going live. The dashboard provides a test interface where you can verify your endpoint works correctly.