API Reference

The GROUNDROCK HTTP API is OpenAI-compatible. If your code already speaks the OpenAI Chat Completions format, you only need to change the base URL.

Chat completion

POSThttps://api.groundrock.dev/v1/chat

Create a chat completion against any supported provider. Streaming, tool calls, structured outputs, and images are supported.

Request parameters

Property	Type	Description
`model`req	`string`	Provider-qualified model ID, e.g. openai/gpt-5.
`messages`req	`Message[]`	Ordered array of role-tagged messages (system, user, assistant, tool).
`fallback`	`string[]`	Ordered list of alternate models to try on failure.
`temperature`	`number`	0.0–2.0. Provider-normalized. Default: 1.
`max_tokens`	`integer`	Maximum completion tokens. Provider-clamped to the model's cap.
`stream`	`boolean`	Enable server-sent events. Default: false.
`cache`	`{ mode: 'off' \| 'exact' \| 'semantic', ttl?: number }`	Per-request cache override. Defaults to the project setting.
`metadata`	`Record<string, string>`	Arbitrary tags surfaced in Logs and Analytics.

Response object

json

{
  "id": "req_01HN...",
  "model": "openai/gpt-5",
  "output_text": "Ship it.",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Ship it." },
    "finish_reason": "stop"
  }],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 3,
    "total_tokens": 15,
    "cost_usd": 0.00021
  },
  "latency_ms": 182,
  "provider": "openai",
  "cache_hit": false
}

Errors

GROUNDROCK normalizes every provider error to a single taxonomy. See Errors for the full list.