Pushary REST API reference

The Pushary REST API is published as an OpenAPI 3.1 document. Point a client generator, an agent framework, or your own tooling at it directly.

curl -s https://pushary.com/openapi.json | jq '.info.title, (.paths | keys | length)'

Authentication

Every endpoint takes a Pushary API key as a bearer token:

curl https://pushary.com/api/v1/server/identity \
  -H "Authorization: Bearer pk_xxx.sk_xxx"

For a Partner integration, create a server-side key in Dashboard → Agent → Settings. For your own coding agent, use npx @pushary/agent-hooks setup. See API keys for scopes and rotation.

The MCP endpoint additionally accepts OAuth 2.0. Discovery starts at /.well-known/oauth-protected-resource, which names the authorization server.

Errors

Errors are JSON with an error message. Shared authentication and validation errors also include diagnostic fields, as below. Some endpoint errors return fewer fields. Branch on the HTTP status and code when present, not the human-readable message.

{
  "error": "Unauthorized",
  "code": "unauthorized",
  "status": 401,
  "message": "Invalid or missing API key. Use Authorization: Bearer pk_xxx.sk_xxx",
  "hint": "Create a key with `npx @pushary/agent-hooks setup`, or in Dashboard > Agent > Settings.",
  "documentation": "https://pushary.com/docs/agents/api-key"
}

A request to a path with no endpoint behind it returns the same shape with code: "not_found" and an openapi field pointing back at the specification.

Common shared code values are unauthorized, forbidden, invalid_request, not_found, method_not_allowed and rate_limited.

Function calling

Published operations carry an operationId and request/response schemas. Use these to build tool definitions for an OpenAPI-aware agent framework. The example below extracts an operation index; map each operation's schemas separately for your framework.

const spec = await fetch('https://pushary.com/openapi.json').then((r) => r.json())

const tools = Object.entries(spec.paths).flatMap(([path, item]) =>
  Object.entries(item)
    .filter(([method]) => ['get', 'post', 'patch', 'delete'].includes(method))
    .map(([method, op]: [string, any]) => ({
      name: op.operationId,
      description: op.description,
      path,
      method,
    })),
)

SDKs

Use a server SDK for Partner integrations. The ask helper creates a decision and polls for an answer within a bounded wait. Persist decision IDs in your workflow, supply a stable idempotency key across retries, and handle transient HTTP failures in your application; SDK requests do not automatically retry.

• TypeScript: npm install @pushary/server
• Python: pip install pushary

See Framework adapters for the Vercel AI SDK, LangGraph, CrewAI, Mastra, Eve and the OpenAI Agents SDK.

What the API covers

Markdown for agents

Any documentation or blog URL serves raw Markdown two ways: append .md, or send an Accept: text/markdown header.

curl -H "Accept: text/markdown" https://pushary.com/docs/agents/reference/api
curl https://pushary.com/docs/agents/reference/api.md