API

Chat completions

POST /api/v1/chat/completions with a personal API key.

POST /api/v1/chat/completions takes a personal API key (Settings, then API keys) as Authorization: Bearer. The key needs the text scope. POST /v1/chat/completions is the in-agent proxy. It checks a different token and is not this API.

Request

• JSON body with a messages array. Anything else is 400 “expected a chat completion request”.
• The body must be present and at most 36 MB. Empty is 400. Larger is 413. Both say “request body missing or too large”.
• model is hawkeye (the account manager) or agent:<id>. Anything else is 400. A key bound to one agent ignores the model you send and uses that agent.
• stream true switches the response to server-sent events. See Streaming.
• Attachments sit on a user message. See Attachments. They need the files scope.

curl -s https://hawkeye.brownhawke.engineering/api/v1/chat/completions \
  -H "Authorization: Bearer $HAWKEYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"hawkeye","messages":[{"role":"user","content":"Summarise the open jobs."}]}'

const res = await fetch(process.env.HAWKEYE_HOST + "/api/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.HAWKEYE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "agent:receptionist",
    messages: [{ role: "user", content: "What is on this drawing?" }],
  }),
});
const data = await res.json();

import os, requests
r = requests.post(
    os.environ["HAWKEYE_HOST"] + "/api/v1/chat/completions",
    headers={"Authorization": "Bearer " + os.environ["HAWKEYE_API_KEY"]},
    json={
        "model": "hawkeye",
        "messages": [{"role": "user", "content": "Summarise the open jobs."}],
    },
    timeout=120,
)
r.raise_for_status()
print(r.json()["choices"][0]["message"]["content"])

Response

A non-streaming response is a chat completion object: object is chat.completion, and the choice finish_reason is stop. When the turn is still running as a job, the response can include X-Hawkeye-Job-Id, X-Hawkeye-Job-State, and X-Hawkeye-Job-Poll-Url.

GET /api/v1/models lists hawkeye and agent:<id> for agents this key may use. It needs the text scope.

Errors

This route uses an OpenAI-style error, not the partner {ok, error, code} envelope. 401 is authentication_error. 402 is insufficient_quota. 403 and 429 are permission_error. The partner code string is still included when the key check produced one, such as scope_denied or agent_denied.