Introduction

The Coda API is an OpenAI-compatible chat-completions endpoint. If you already use the OpenAI SDKs or any tool that speaks that format, you only need to change two things: the base_url and your api_key.

Every request is authenticated with an ik_live_ key you create in the dashboard, rate-limited per key, and metered so you can track usage.

Authentication

Authenticate by sending your secret key in the Authorization header as a Bearer token. Keys are created — and shown exactly once — in the dashboard.

Authorization header

Authorization: Bearer ik_live_...

Keep your key secret. It is stored as a hash on our side — if you lose it, revoke it and create a new one. Never embed it in client-side / browser code.

Base URL

All endpoints are served under a single base URL:

https://your-coda-host/api/v1

Chat completions

POST /chat/completions

Send a list of messages and receive a model completion. This mirrors the OpenAI chat-completions schema.

Request

curl https://your-coda-host/api/v1/chat/completions \
  -H "Authorization: Bearer $CODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user",   "content": "Write a haiku about the terminal." }
    ]
  }'

Response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "coda",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Black cursor blinking..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 17, "total_tokens": 41 }
}

Parameters

The request body accepts the standard chat-completions fields:

messages	array	Required	List of message objects, each with a role (system / user / assistant) and content.
model	string	Optional	Defaults to the Coda model. You can pass "coda" or leave it out.
stream	boolean	Optional	If true, tokens are streamed back as server-sent events. Default false.
temperature	number	Optional	Sampling temperature. Higher = more random.
max_tokens	number	Optional	Maximum tokens to generate in the completion.
top_p	number	Optional	Nucleus sampling. Alternative to temperature.
stop	string \| array	Optional	Up to 4 sequences where generation stops.

Streaming

Set "stream": true to receive the response incrementally as server-sent events (SSE).

Streaming request

curl https://your-coda-host/api/v1/chat/completions \
  -H "Authorization: Bearer $CODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "messages": [{ "role": "user", "content": "Count to five." }]
  }'

Stream chunks

data: {"choices":[{"delta":{"content":"One"}}]}
data: {"choices":[{"delta":{"content":", two"}}]}
data: {"choices":[{"delta":{"content":", three..."}}]}
data: [DONE]

Models

You don't need to pick a specific upstream model — Coda maps requests to its default coding model automatically. Pass "model": "coda" (or omit model entirely) and you'll get the current best model behind the API.

Rate limits

Each key is limited to 120 requests per minute on a sliding window.

X-RateLimit-Limit	header	Max requests allowed in the window.
X-RateLimit-Remaining	header	Requests left in the current window.
Retry-After	header	Seconds to wait, sent only on a 429 response.

Errors

Errors are returned as JSON with an error object and an HTTP status:

Error shape

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid or revoked API key."
  }
}

400	invalid_request_error	Malformed JSON or missing messages array.
401	authentication_error	Missing, invalid, or revoked API key.
429	rate_limit_error	Too many requests — slow down.
502	api_error	Could not reach the upstream provider.
500	api_error	Server misconfiguration.

Using the Coda CLI

The Coda CLI speaks this API natively.

Terminal

npm install -g coda-cli

export CODA_API_KEY=ik_live_...
coda --base-url https://your-coda-host/api/v1 --api-key $CODA_API_KEY

# or just start chatting
coda "refactor this file and add tests"

Libraries

Any OpenAI-compatible SDK works.

Python

from openai import OpenAI

client = OpenAI(base_url="https://your-coda-host/api/v1", api_key="ik_live_...")

resp = client.chat.completions.create(
    model="coda",
    messages=[{"role": "user", "content": "Hello from coda"}],
)
print(resp.choices[0].message.content)

Node / TypeScript

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://your-coda-host/api/v1", apiKey: "ik_live_..." });

const resp = await client.chat.completions.create({
  model: "coda",
  messages: [{ role: "user", content: "Hello from coda" }],
});
console.log(resp.choices[0].message.content);