API reference · Cobble Docs

Base URL for everything:

code

https://api.cobble.network/v1

Authentication on every request:

code

Authorization: Bearer $COBBLE_API_KEY

Cobble implements the OpenAI-compatible API surface. If a parameter works with the OpenAI SDK, send it the same way here; unsupported parameters are ignored rather than rejected, so existing code runs unmodified.

GET /v1/models

Returns every model your key can access, with catalog IDs. This is the source of truth — model IDs in docs or blog posts can go stale; this endpoint cannot.

bash

curl https://api.cobble.network/v1/models \
  -H "Authorization: Bearer $COBBLE_API_KEY"

POST /v1/chat/completions

The primary generation endpoint.

Parameter	Type	Notes
`model`	string, required	Catalog ID, exactly as `/v1/models` returns it
`messages`	array, required	Standard role/content messages (`system`, `user`, `assistant`, `tool`)
`stream`	bool	Server-sent events; final chunk carries `usage`
`max_tokens`	int	Cap on generated tokens
`temperature`, `top_p`	float	Sampling controls
`stop`	string or array	Stop sequences
`tools`, `tool_choice`	array / string	OpenAI-format tool calling; supported on all generative models unless the catalog says otherwise
`response_format`	object	`{"type": "json_object"}` for JSON mode
`seed`	int	Best-effort determinism

Response follows the OpenAI schema: choices[].message, finish_reason, and usage with prompt_tokens, completion_tokens, and cached_tokens when prompt caching applied.

Streaming

Set stream: true and read server-sent events. Each event is a chat.completion.chunk; the stream ends with data: [DONE]. If a stream drops mid-response, retry the whole request — chunks are not resumable.

Prompt caching

Repeated prompt prefixes (system prompts, long documents) are cached automatically — no API changes needed. Cached tokens are billed at the reduced cached rate shown in the catalog for wallet-billed requests; for in-plan requests caching just makes responses faster.

POST /v1/embeddings

bash

curl https://api.cobble.network/v1/embeddings \
  -H "Authorization: Bearer $COBBLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "nomic/nomic-embed-1.5", "input": ["first text", "second text"]}'

input accepts a string or array of strings. Embeddings are billed from your wallet at catalog rates — see Limits & billing.

OCR

OCR models process documents per page, billed from your wallet. Submit a document and receive structured text back:

bash

curl https://api.cobble.network/v1/ocr \
  -H "Authorization: Bearer $COBBLE_API_KEY" \
  -F "model=deepseek/deepseek-ocr2" \
  -F "file=@contract.pdf"

See Documents & embeddings for choosing between the four OCR models and a full document pipeline example.

Errors

Errors use the OpenAI error envelope: {"error": {"message", "type", "code"}}. Every response includes a request ID header — include it when contacting support.

Status	Meaning	What to do
`400`	Malformed request	The `message` field says which parameter; nothing to retry
`401`	Bad or missing key	Fix the `Authorization` header; don't retry
`403`	Model not on your plan, wallet spending off	Enable spillover, top up, or upgrade — see Limits & billing
`404`	Unknown model ID	Copy the exact ID from `/v1/models`
`429`	Window exhausted or concurrency limit	Honor `Retry-After`; enable spillover for uninterrupted agents
`500` / `503`	Server-side problem	Retry with exponential backoff (start at 1s, cap at 30s); check the status page

Retry guidance

Retry 429 and 5xx only. Use exponential backoff with jitter. Requests that fail before generation starts are not billed and don't count against your window. For agents, prefer enabling a small wallet spend cap over aggressive retry loops — retrying into an exhausted window just burns time.

Model stability

Published model IDs are never renamed or silently swapped. When a model is scheduled for removal we announce it in the changelog and keep it serving for at least 60 days after the announcement. If you want automatic upgrades to our current best pick for a task, use a capability alias (coming soon) instead of pinning a specific model.