Gateway API Reference

Base URL: https://api.clawpipe.ai. The gateway is an OpenAPI 3.1 compliant service running on Cloudflare Workers.

Authentication

The API supports two authentication methods:

API Key (Bearer) — for SDK and programmatic access. Pass as Authorization: Bearer cp_xxx with X-Project-Id header.
JWT Cookie — for dashboard and browser access. Set via clawpipe_session HttpOnly Secure cookie after login.

API keys are hashed with SHA-256 and never stored in plaintext. Provider keys are encrypted at rest in KV.

Prompt Endpoints

POST /v1/prompt

Send a prompt through the pipeline and receive a complete response.

Request Body

{
  "prompt": "Explain recursion in simple terms",
  "provider": "openai",
  "model": "gpt-4o-mini",
  "system": "You are a helpful tutor",
  "maxTokens": 4096,
  "temperature": 0.7
}

Response (200)

{
  "text": "Recursion is when a function calls itself...",
  "tokensIn": 24,
  "tokensOut": 156,
  "latencyMs": 412
}

Errors: 400 invalid request, 401 auth failed, 502 provider error, 503 provider not configured.

POST /v1/stream

Stream a prompt response via Server-Sent Events. Same request body as /v1/prompt.

Response (200)

Content-Type: text/event-stream

data: Recursion
data:  is when
data:  a function
data:  calls itself...
data: [DONE]

Auth Endpoints

POST /auth/register

Create a new account. Sets a session cookie on success.

{ "email": "dev@example.com", "password": "min8chars", "name": "Dev" }

Returns: 201 created, 400 validation error, 409 email taken.

POST /auth/login

{ "email": "dev@example.com", "password": "min8chars" }

Returns: 200 authenticated, 401 invalid credentials.

GET /auth/me

Get the current authenticated user profile. Requires session cookie.

POST /auth/logout

Sign out and clear the session cookie.

GET /auth/google

Redirect to Google OAuth 2.0 flow. Returns 302.

GET /auth/github

Redirect to GitHub OAuth flow. Returns 302.

Project Endpoints

GET /v1/projects

List all projects for the authenticated user with their roles.

POST /v1/projects

Create a new project. Returns the project with an initial API key.

{ "name": "my-new-project" }

POST /v1/projects/:projectId/keys

Create a new API key for a project. Requires admin+ role. The key is shown once.

DELETE /v1/projects/:projectId/keys

Revoke an API key. Requires owner role.

POST /v1/projects/:projectId/keys/rotate

Rotate an API key. Issues a new key and invalidates the old one. Requires owner role.

Analytics Endpoints

GET /v1/analytics/overview

Aggregate statistics for the project: total requests, tokens, cost, cache hit rate.

GET /v1/analytics/providers

Per-provider and per-model request counts and cost breakdown.

GET /v1/analytics/cache

Daily cache hit rates and savings data.

GET /v1/analytics/routes

Daily routing decisions by model, showing how the self-learning router is distributing traffic.

Weights Endpoints

GET /v1/weights

Get the learned router weights for the project.

PUT /v1/weights

Save updated router weights.

{ "weights": [{ "provider": "openai", "model": "gpt-4o", "score": 0.85 }] }

Health Check

GET /health

No authentication required. Returns gateway status.

{ "status": "ok", "service": "clawpipe-gateway" }