Pikes API Reference

Base URL: https://pikes.ai

There are two ways into Pikes programmatically, and they run the same tools over the same account:

Every call runs as a Pikes user and spends that user's credits. There is no team- or org-level credential today; see Workspace scoping before you plan around it.

• MCP protocol: 2025-06-18 (also accepts 2024-11-05)
• Transports: streamable_http, http_sse
• OAuth scopes: generate_image, edit_image, expand_image, read_images
• Published at https://pikes.ai/docs/api, linked from Settings → API and Settings → Claude / MCP
• Verified against https://pikes.ai on 2026-08-25

These facts and the tool catalogue below are written by server/__tests__/api-surface-probe.js from a live server — see Verifying this document.

Authentication#

OAuth 2.1 (MCP clients)#

Standard discovery — point a compliant MCP client at https://pikes.ai/mcp and it will find everything itself:

• GET/.well-known/oauth-authorization-server
• GET/.well-known/oauth-protected-resource

PKCE is required (S256). Grants: authorization_code, refresh_token. Scopes: generate_image, edit_image, expand_image, read_images.

API keys (headless)#

Keys look like psk_…, are stored only as a SHA-256 hash, and are accepted two ways:

Authorization: Bearer psk_…
x-api-key: psk_…

Create one in the app under Settings → API (or Settings → Claude / MCP for a key you'll paste into an MCP client), or over the API. Key management is authenticated by the user's session JWT, never by a key — a key cannot mint or revoke keys.

# Create
curl -X POST https://pikes.ai/api/keys \
  -H "Authorization: Bearer <SUPABASE_SESSION_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name": "orchestrator"}'

# → { "success": true, "key": { "id": "...", "name": "orchestrator",
#     "keyPrefix": "psk_754fed7b...", "rawKey": "psk_…", "createdAt": "..." } }

rawKey is returned once. Store it then; it cannot be read back.

curl https://pikes.ai/api/keys -H "Authorization: Bearer <JWT>"          # list (metadata only)
curl -X DELETE https://pikes.ai/api/keys/<keyId> -H "Authorization: Bearer <JWT>"   # revoke

Listing returns id, name, key_prefix, created_at, last_used_at, revoked — never key material. Revoking a key you don't own returns 404.

Scope difference worth knowing: API-key calls carry generate_image, edit_image, expand_image. OAuth additionally carries read_images.

REST tool calls#

POST/mcp/tools/:toolName — the whole tool catalogue as ordinary HTTP. The body is the tool's arguments; no JSON-RPC envelope.

curl -X POST https://pikes.ai/mcp/tools/generate_image \
  -H "x-api-key: psk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Amber supplement bottle on warm marble, soft window light",
    "aspectRatio": "4:5",
    "model": "consistency_pro",
    "resolution": "2K"
  }'

Responses come back in MCP content-block form. The payload is JSON encoded inside text:

{ "content": [ { "type": "text", "text": "{\"success\":true,\"images\":[…]}" } ] }

Tool-level failures return HTTP 200 with "isError": true and the reason in the same block — check isError, not just the status code:

{ "content": [ { "type": "text", "text": "{\"success\":false,\"error\":\"Could not fetch account info\"}" } ], "isError": true }

Missing or bad credentials return 401:

{ "error": "Unauthorized",
  "message": "OAuth token or API key required. Authorize at /mcp/oauth/authorize or use x-api-key header" }

MCP transport#

• POST/mcp — Streamable HTTP, JSON-RPC 2.0 (initialize, tools/list, tools/call, resources/*, prompts/*). Protocol 2025-06-18, with 2024-11-05 still accepted.
• POST/mcp/sse + POST/mcp/message — the deprecated SSE transport, kept for older clients.
• GET/mcp — server info: transports, auth URLs, and the live tool list.

Discovery is open on purpose: initialize and tools/list answer without credentials, so a client can inspect the catalogue before anyone authorizes it. Executing a tool always needs one.

curl -X POST https://pikes.ai/mcp \
  -H "Authorization: Bearer psk_…" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude Code, for reference:

claude mcp add --transport http pikes-ai https://pikes.ai/mcp

Tool catalogue#

29 tools, as reported by tools/list.

Image and video

Async jobs

Products, brand and account

Boards

Research

Meta Ads and everything else

GET/mcp returns the same list with full schemas.

Common parameters#

Product identity is reference-conditioned, not fine-tuned: pass the actual pack shots as imageUrls (or let get_product_images fetch them from the product library) and the model works from those pixels. New packaging = new reference images, no retraining step.

Long renders#

4K and video can outrun an HTTP timeout. Submit and poll instead:

curl -X POST https://pikes.ai/mcp/tools/submit_image_job \
  -H "x-api-key: psk_…" -H "Content-Type: application/json" \
  -d '{"tool":"generate_image","prompt":"…","resolution":"4K"}'
# → jobId

curl -X POST https://pikes.ai/mcp/tools/get_image_job \
  -H "x-api-key: psk_…" -H "Content-Type: application/json" \
  -d '{"jobId":"…"}'

Credits are charged once, when the job runs. Jobs are scoped to the caller.

Product-shot endpoints#

Two multipart endpoints for the simplest case — send a file, get a finished shot.

curl -X POST https://pikes.ai/api/product-shot \
  -H "x-api-key: psk_…" \
  -F "image=@bottle.jpg" \
  -F "aspect_ratio=4:5" \
  -F "resolution=4K"

1K runs Nano Banana; 4K runs Nano Banana Pro. Success:

{ "success": true, "image": { "url": "…" }, "creditsUsed": 12 }

Cost today: 6 credits at 1K, 12 credits at 4K. Rate limit: 30 requests per minute per key. Credits are pre-charged and refunded automatically if the render fails.

Errors#

MCP tool calls that fail for content or upstream reasons return 200 with isError: true rather than an HTTP error.

Only the product-shot endpoints are rate limited today. On /mcp and /mcp/tools/* the practical ceiling is the account's credit balance — build your own backoff if you fan out hard.

Workspace scoping#

A credential identifies one user, and calls execute in that user's personal workspace: assets created over the API land with no team attached, whatever teams the user belongs to. list_teams exists so a board can be shared with a team after the fact, but there is no way to say "run this call as the ACME workspace."

Practical consequences for a multi-seat evaluation:

• Two users running the same brief will not see each other's product library or Context unless those were created in a shared team through the app.
• Assets generated headlessly won't appear in a team workspace by themselves.

If a connection that belongs to a team rather than a person is a requirement, treat it as a roadmap item, not a configuration flag.

Verifying this document#

server/__tests__/api-surface-probe.js exercises this surface end to end and rewrites the generated blocks above from what the server answered, so the doc cannot quietly drift from the API.

# against a local server (PORT=5099 node -r ./__tests__/boot-stub.js index.js)
node server/__tests__/api-surface-probe.js

# against production, no account needed — discovery, transport, auth negatives
node server/__tests__/api-surface-probe.js --base https://pikes.ai --quick

# refresh the generated blocks in this file
node server/__tests__/api-surface-probe.js --write-docs

# include one real 1K render (~6 credits)
node server/__tests__/api-surface-probe.js --generate

It covers discovery and PKCE advertisement, the auth negatives (no credential, bogus key, minting a key without a session), the key lifecycle across two accounts including cross-account revoke, initialize and tools/list, a REST tool call and its content-block envelope, revocation actually killing a key, and whether every live tool is documented here. A full run creates two throwaway users and deletes them; --quick creates nothing. Exit code is non-zero on any failure, so it drops straight into a loop or a scheduled check.

Data and billing notes#

• Generated assets are stored in the caller's Pikes library and are retrievable through the board and asset tools.
• Credits are charged per generation, by model and resolution; creditsUsed is returned where a call charges directly. A failed render is refunded.
• Data governance, incident response, and third-party risk policies live in docs/policies/.