Developer API

Ricochet Code API

Ricochet coding automation has a hosted model gateway, budget checks, usage reporting, premium approvals, and a Cloud Bridge for remote IDE control.

#Budget and usage

Check available ricochet_code credits, report usage, and request premium approval decisions.

Method	Endpoint	Auth	Scope	Audience	Description
GET	`/ricochet/budget`	API key	ricochet_code	Ricochet clients	Check ricochet_code credits, plan, window limits, task limits, and upgrade URL before a hosted AI run.
POST	`/ricochet/usage/quote`	API key	ricochet_code	Ricochet clients	Quote and reserve hosted Ricochet usage before calling an upstream model.Use before the upstream hosted-model call.
POST	`/ricochet/usage/report`	API key	ricochet_code	Ricochet clients	Report hosted model usage with idempotency, token counts, provider, model, and billing metadata.
GET	`/ricochet/usage`	API key	ricochet_code	Ricochet clients	List Ricochet hosted usage events with filters for session, run, provider, model, and limit.
POST	`/ricochet/usage/approve-premium`	API key	ricochet_code	Ricochet clients	Store a temporary approval for premium model usage in a task, run, or session.
GET	`/ricochet/sessions`	User token	-	Ricochet clients	List Ricochet IDE and device sessions for the current user.
DELETE	`/ricochet/sessions/:id`	User token	-	Ricochet clients	Revoke a Ricochet IDE or device session.

GET/ricochet/budget

Check ricochet_code credits, plan, window limits, task limits, and upgrade URL before a hosted AI run.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

POST/ricochet/usage/quote

Quote and reserve hosted Ricochet usage before calling an upstream model.Use before the upstream hosted-model call.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

POST/ricochet/usage/report

Report hosted model usage with idempotency, token counts, provider, model, and billing metadata.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

GET/ricochet/usage

List Ricochet hosted usage events with filters for session, run, provider, model, and limit.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

POST/ricochet/usage/approve-premium

Store a temporary approval for premium model usage in a task, run, or session.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

GET/ricochet/sessions

List Ricochet IDE and device sessions for the current user.

Auth: User tokenScope: -Audience: Ricochet clients

DELETE/ricochet/sessions/:id

Revoke a Ricochet IDE or device session.

Auth: User tokenScope: -Audience: Ricochet clients

#Hosted model gateway

Use the legacy Ricochet chat completions alias for existing coding clients. New generic model access should use the AI Gateway.

Example

curl "https://api.grik.io/api/v1/ricochet/budget?task_id=run_123" \
  -H "Authorization: Bearer GRIK_API_KEY"

curl -X POST https://api.grik.io/api/v1/ricochet/openai/v1/chat/completions \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Idempotency-Key: run_123_turn_1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ricochet-code",
    "messages": [
      {"role": "user", "content": "Review this repository and suggest the first safe fix."}
    ],
    "stream": true
  }'

curl -X POST https://api.grik.io/api/v1/ricochet/openai/v1/responses \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Idempotency-Key: run_123_response_1" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ricochet-code",
    "input": "Review this repository and suggest the first safe fix.",
    "stream": true
  }'

Method	Endpoint	Auth	Scope	Audience	Description
POST	`/ricochet/openai/v1/chat/completions`	API key	ricochet_code	Ricochet clients	Legacy Ricochet hosted coding chat completions alias. Use /chat/completions on the AI Gateway for new generic model integrations.Compatibility route for existing Ricochet clients.
POST	`/ricochet/openai/v1/responses`	API key	ricochet_code	Ricochet clients	Ricochet hosted coding Responses API alias for clients that use OpenAI Responses.Compatibility route for existing Ricochet clients.

POST/ricochet/openai/v1/chat/completions

Legacy Ricochet hosted coding chat completions alias. Use /chat/completions on the AI Gateway for new generic model integrations.Compatibility route for existing Ricochet clients.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients

POST/ricochet/openai/v1/responses

Ricochet hosted coding Responses API alias for clients that use OpenAI Responses.Compatibility route for existing Ricochet clients.

Auth: API keyScope: ricochet_codeAudience: Ricochet clients