Docs / API
API
OpenAI-compatible. Same account and same credits as the app. Point any OpenAI SDK at AskPuck and change the model name.
BASE
https://askpuck.app/v1Authentication#
Create a key in Dashboard → API keys. It's shown once. Send it as a Bearer token:
Authorization: Bearer sk-puck-…
A key spends your credits. Keep it on a server, never in a web page or in git.
Chat completions#
POST
https://askpuck.app/v1/chat/completionscurl https://askpuck.app/v1/chat/completions \ -H "Authorization: Bearer $PUCK_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "puck-cortex-1.2", "messages": [{"role": "user", "content": "Hello"}] }'
import os from openai import OpenAI client = OpenAI( base_url="https://askpuck.app/v1", api_key=os.environ["PUCK_KEY"], ) r = client.chat.completions.create( model="puck-cortex-1.2", messages=[{"role": "user", "content": "Hello"}], ) print(r.choices[0].message.content)
import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://askpuck.app/v1", apiKey: process.env.PUCK_KEY, }); const r = await client.chat.completions.create({ model: "puck-cortex-1.2", messages: [{ role: "user", content: "Hello" }], }); console.log(r.choices[0].message.content);
Body
| Field | What it does |
|---|---|
| modelrequiredstring | puck-cortex-1.2. See Models. |
| messagesrequiredarray | The chat so far, in OpenAI format: system, user, assistant. |
| streamoptionalboolean | Send tokens as they arrive (server-sent events). The last chunk carries usage. |
| max_tokensoptionalinteger | Cap on the reply. Held to 256k and to what's left of the 1M window. |
Response
{
"object": "chat.completion",
"model": "cortex-1.2",
"choices": [{
"index": 0,
"message": { "role": "assistant", "content": "Hi! What are we building?" },
"finish_reason": "stop"
}],
"usage": { "prompt_tokens": 9, "completion_tokens": 8, "total_tokens": 17 }
}Streaming#
With "stream": true the reply comes as data: lines, one chunk each, closed by data: [DONE]. Closing the request cancels the call: you pay only for tokens already made.
List models#
GET
https://askpuck.app/v1/models{
"object": "list",
"data": [
{ "id": "cortex-1.2", "context_length": 1048576, "max_output_tokens": 256000 }
]
}Errors and limits#
Errors come in the OpenAI shape: {"error": {"message", "type", "code"}}.
| Status | Type | When |
|---|---|---|
| 400 | invalid_request_error | The body isn't valid JSON. |
| 401 | authentication_error | Missing, wrong or revoked key. |
| 402 | invalid_request_error | No credits left. Top up on the dashboard. |
| 413 | invalid_request_error | Request larger than 32 MB. |
| 429 | rate_limit_error | Over 10 requests per second. Wait for retry-after. |
| 5xx | server_error | Our side. Retry after a moment. |
| Limit | Value |
|---|---|
| Rate | 10 requests / second / account, all keys together |
| Context | 1M tokens |
| Output | 256k tokens |
| Price | Same token prices as the app. A call smaller than $0.0001 is free. |
| Credits | Same balance as the app |
Something unclear or wrong?Tell us on Discord →