Building Custom Agents

Prefer writing your own agent to using Zapier or n8n? The REST API, OpenAPI spec, and outbound webhooks give you everything you need.

Core building blocksCopy Anchor Link

1. Personal access token — mint with narrow abilities. See authentication.
2. OpenAPI spec — https://api.subscriby.net/openapi.json. Feed it to your favourite code-gen tool (openapi-generator, Stainless, Speakeasy).
3. Typed SDK — optional; a generated client beats hand-rolled fetch calls once your surface gets non-trivial.
4. Outbound webhooks — for event-driven work. Sign-verify per security guide.
5. Idempotency — every write takes Idempotency-Key. Your SDK should inject a UUID automatically.

Suggested architectureCopy Anchor Link

┌──────────────┐          ┌──────────────────────┐          ┌───────────────┐
│   Your app   │◀─webhook─│  Subscriby API      │◀─REST────│  Your agent   │
│              │  (POST)  │  api.subscriby.net  │          │  (LLM + tools)│
└──────────────┘          └──────────────────────┘          └───────────────┘

• Your agent pushes commands to Subscriby over REST.
• Subscriby pushes state changes back to your app over outbound webhooks.
• The agent can observe state either by polling GET endpoints or by subscribing to its own webhook inbox.

Read-first, write-laterCopy Anchor Link

Most agents should start in read-only mode:

• Token abilities: project:view-any, project-user:view-any, project-subscription-plan:view-any.
• Build and test the retrieval + summary pipeline.
• Only then mint a second token with write abilities and enable the write paths.

Keeping read and write tokens separate limits blast radius on a leak.

Retry and back-off policyCopy Anchor Link

• Always retry on 5xx and 429 with exponential back-off.
• Honour Retry-After when present.
• Use the same Idempotency-Key across retries of the same logical operation so replays are free.

Surfacing errors to the userCopy Anchor Link

Subscriby returns structured errors:

{
  "error": {
    "code": "TOKEN_MISSING_ABILITY",
    "message": "...",
    "docs_url": "https://docs.subscriby.net/api/v1/errors#TOKEN_MISSING_ABILITY",
    "remediation": "Mint a new token that includes the required ability.",
    "request_id": "..."
  }
}

Echo code, message, and docs_url into your agent's failure output. The request_id is worth passing back to support if you need help diagnosing a specific call.

Observing your agent's actionsCopy Anchor Link

Every REST call and MCP tool invocation is logged under activity_log with actor_kind = 'api_token' or 'mcp'. Review in the dashboard, or fetch via GET /v1/activity.

When to use MCP insteadCopy Anchor Link

If the agent is a Claude-family model, MCP gives you typed tool-calls and first-class ability enforcement without an OpenAPI layer. Use MCP for Claude Desktop / Cursor; use the raw REST API when you're running inference on OpenAI, Google, Mistral, or self-hosted models. If the agent is Claude Code itself, the Agentic Kit bundles the server and carries this whole page as a skill, so the credential flow, the read-first rule and the audit trail are followed without being prompted for.