API Reference

Base URL: https://pincerapi.com/api/v1

All endpoints require authentication unless noted. Use Authorization: Bearer pincer_sk_... or X-API-Key: pincer_sk_....

Health

GET /health

Health check. No auth required.

Response: { "ok": true, "status": "healthy" }

APIs (Directory)

GET /apis

List all APIs. No auth required. Supports ?q=search and ?category=weather.

GET /apis/{id}

Get API details. No auth required.

GET /apis/{id}/instructions

Get agent-readable instructions. Costs $0.01.

GET /apis/category/{category}

List APIs in a category. No auth required.

Categories

GET /categories

List all API categories. No auth required.

Proxy

{METHOD} /proxy/{api_id}/{path}

Proxy a request to a third-party API. Auth required. Costs vary by API.

Supports: GET, POST, PUT, PATCH, DELETE. Request body and query params are forwarded.

Response headers include X-Pincer-Cost, X-Pincer-Balance, X-Pincer-Api.

Balance & Billing

GET /balance

Get current balance. Returns { ok: true, balance: 42.50 }.

GET /usage

Get usage summary. Supports ?days=30.

GET /usage/{api_id}

Get usage for a specific API.

GET /usage/stats

Get aggregate usage statistics.

API Keys

GET /keys

List your API keys (prefix + metadata, never the full key).

POST /keys

Create a new API key. Body: { "name": "my-agent" }. Returns the full key once.

PATCH /keys/{id}

Update key (rename, disable/enable).

DELETE /keys/{id}

Revoke a key permanently.

Agent Keys (v1)

GET /agent-keys

List agent API keys.

POST /agent-keys

Create an agent API key.

DELETE /agent-keys/{id}

Delete an agent API key.

Connections

POST /connect/{api_id}

Connect to an API (BYOK — store your API key). Body: { "apiKey": "your-key" }.

GET /me/apis

List your connected APIs.

Cookbooks

GET /cookbooks

List all cookbooks. No auth required. Supports ?q=search and ?category=....

GET /cookbooks/{id}

Get cookbook details with steps and API slots. Costs $0.005.

POST /cookbooks/{id}/start

Start a cookbook session. Body: { "selectedApis": { "slot": "api_id" } }.

GET /cookbooks/sessions

List your active sessions.

GET /cookbooks/sessions/{sessionId}

Get session status and progress.

GET /cookbooks/sessions/{sessionId}/step

Get current step details.

POST /cookbooks/sessions/{sessionId}/complete-step

Complete current step. Body: { "stepId": "...", "resultData": { ... } }.

GET /cookbooks/sessions/{sessionId}/events

SSE stream of session events.

GET /cookbooks/sessions/{sessionId}/human-steps

Get pending human steps.

Docs

GET /docs

List all doc sections (id, title, summary). Auth required. Free.

GET /docs/{slug}

Get full doc content. Auth required. Costs $0.005.

GET /docs/search?q=query

Search docs. Returns matching titles + snippets. Auth required. Free.

Discovery

GET /discover

Discover APIs based on a natural-language query. No auth required.

Voting

POST /vote

Vote on an API or cookbook. Body: { "targetType": "api"|"cookbook", "targetId": "...", "value": 1|-1 }.

GET /votes?targetType=...&targetId=...

Get vote tallies.

Registration

POST /register

Register a new account. Body: { "email": "...", "password": "..." }.