AI Gateway APIGRIKAI API

Developer API

AI Gateway API

Use one GRIKAI API key and one OpenAI-compatible base URL for multiple model providers, pay-as-you-go USD balance, routing, fallbacks, logs, and spend controls.

Quickstart

Create an ai.gateway key, use https://api.grik.io/api/v1 as the OpenAI SDK base URL, and call the shared model gateway.

Example
curl -X POST https://api.grik.io/api/v1/keys \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Gateway production",
    "scopes": ["ai.gateway"],
    "product": "ai_gateway",
    "environment": "production",
    "spend_limit_micros": 50000000,
    "spend_reset_interval": "monthly"
  }'

curl https://api.grik.io/api/v1/models \
  -H "Authorization: Bearer GRIK_API_KEY"

Models

List the model catalog with provider availability, context length, customer-visible pricing, capabilities, and data policy metadata.

GET/models

List AI Gateway models with provider availability, context length, pricing, capabilities, and data policy metadata.

Auth: Optional bearerScope: -Audience: Developers

Chat completions

Send OpenAI/OpenRouter-compatible chat requests with streaming, tools, response_format, app attribution headers, and idempotency.

Example
curl -X POST https://api.grik.io/api/v1/chat/completions \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Idempotency-Key: chat_123" \
  -H "HTTP-Referer: https://your-app.example" \
  -H "X-Title: Your App" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Summarize this changelog in three bullets."}
    ],
    "stream": true
  }'
POST/chat/completions

Run OpenAI/OpenRouter-compatible chat completions through the GRIKAI AI Gateway with streaming, tools, fallbacks, and provider routing.Send Idempotency-Key for user-triggered create/retry requests.

Auth: API keyScope: ai.gatewayAudience: Developers

Responses API

Send OpenAI Responses-compatible requests. The gateway routes native OpenAI/xAI Responses, Anthropic Messages, and OpenAI-compatible providers behind the same endpoint.

Example
curl -X POST https://api.grik.io/api/v1/responses \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Idempotency-Key: resp_123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "input": "Summarize this changelog in three bullets.",
    "max_output_tokens": 600,
    "provider": {
      "allow_fallbacks": true,
      "sort": "price"
    }
  }'
POST/responses

Run OpenAI Responses-compatible requests through the GRIKAI AI Gateway with the same model catalog, routing, fallbacks, and usage billing.Send Idempotency-Key for user-triggered create/retry requests.

Auth: API keyScope: ai.gatewayAudience: Developers
POST/responses/input_tokens

Count Responses input tokens before execution. OpenAI-backed models use upstream token counting; other providers return an estimated count.Use before the upstream hosted-model call.

Auth: API keyScope: ai.gatewayAudience: Developers

Routing and fallbacks

Use models fallback arrays and provider routing fields such as order, only, ignore, allow_fallbacks, and sort.

Example
curl -X POST https://api.grik.io/api/v1/chat/completions \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "models": ["openai/gpt-4o-mini", "minimax/minimax-m3"],
    "provider": {
      "order": ["openrouter", "ricochet"],
      "ignore": ["experimental-provider"],
      "allow_fallbacks": true,
      "sort": "price"
    },
    "messages": [
      {"role": "user", "content": "Generate a release-risk checklist."}
    ]
  }'

Preflight and balance

Check live model pricing, count input tokens, estimate request cost, and verify available AI Gateway balance before running a model call. Balance top-ups are handled in the signed-in account dashboard.

Example
curl https://api.grik.io/api/v1/ai-gateway/balance \
  -H "Authorization: Bearer GRIK_API_KEY"

curl -X POST https://api.grik.io/api/v1/responses/input_tokens \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.5",
    "input": "Summarize this changelog in three bullets."
  }'

curl -X POST https://api.grik.io/api/v1/ai-gateway/quote \
  -H "Authorization: Bearer GRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "responses",
    "model": "openai/gpt-5.5",
    "input": "Summarize this changelog in three bullets.",
    "max_output_tokens": 600
  }'
GET/ai-gateway/balance

Return balance_micros, pending reservation micros, available balance, and USD display values.

Auth: API keyScope: ai.gatewayAudience: Developers
GET/ai-gateway/pricing

Return AI Gateway packages, platform fee, minimum charge, and customer-visible model pricing.

Auth: Optional bearerScope: -Audience: Developers
POST/responses/input_tokens

Count Responses input tokens before execution. OpenAI-backed models use upstream token counting; other providers return an estimated count.Use before the upstream hosted-model call.

Auth: API keyScope: ai.gatewayAudience: Developers
POST/ai-gateway/quote

Estimate tokens, customer charge, available balance, spend-limit decision, and fallback-route charge before execution. This does not reserve or charge balance.Use before the upstream hosted-model call.

Auth: API keyScope: ai.gatewayAudience: Developers

Usage logs

Inspect settled usage events, route attempts, failed reservations, provider costs, customer charges, and margin fields.

GET/ai-gateway/usage

List AI Gateway usage events with provider, model, status, date, and limit filters.

Auth: API keyScope: ai.gatewayAudience: Developers
GET/ai-gateway/usage/:id

Fetch one usage event with token counts, provider cost, platform fee, charge, route attempts, and metadata.

Auth: API keyScope: ai.gatewayAudience: Developers
GET/ai-gateway/reservations

List active, failed, and settled preflight reservations for idempotency and pending-balance debugging.

Auth: API keyScope: ai.gatewayAudience: Developers

API keys

Manage ai.gateway keys, disabled status, environment labels, spend limits, reset windows, and usage totals.

GET/keys

List account API keys without exposing the raw secret.

Auth: User tokenScope: -Audience: Developers
POST/keys

Create an API key with ai.gateway scope and optional spend controls. The raw key is returned only once.

Auth: User tokenScope: -Audience: Developers
PATCH/keys/:id

Update key name, status, scopes, environment, spend limit, or reset interval without rotating the secret.

Auth: User tokenScope: -Audience: Developers
DELETE/keys/:id

Revoke an API key by id.

Auth: User tokenScope: -Audience: Developers

Errors

Clients should branch on OpenAI-compatible error.type, error.code, and HTTP status for billing and retry decisions.

CodeDescription
402

Insufficient credits, budget exceeded, or premium approval required.

403

The API key is valid but does not include the scope required for the endpoint.

429

The API key or organization exceeded the current request limit.

503

No configured provider route is available or the upstream provider failed.