One endpoint.
Every answer. ask.hailey.io

Three lines of setup in any OpenAI client — only the base URL changes.

curl https://ask.hailey.io/v1/chat/completions \
  -H "Authorization: Bearer $HAILEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "Hello, Hailey."}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://ask.hailey.io/v1",
    api_key="hly_…",
)

resp = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Hello, Hailey."}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ask.hailey.io/v1",
  apiKey: process.env.HAILEY_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "claude-opus-4-8",
  messages: [{ role: "user", content: "Hello, Hailey." }],
});
console.log(resp.choices[0].message.content);

Every request needs a service key in the Authorization header: Authorization: Bearer hly_…. Keys are created per integration on the API keys page, are shown once at creation, and can be revoked at any time.

Each key can carry a default project — the context it runs in when a request doesn't name one (see Projects).

GET /v1/models lists the models your key can use. A model id pins the engine (the AI backend adapter), the model family, and the version in one string — pick the id, and the gateway routes to the right backend.

Additional engines (e.g. OpenAI-family models) appear in this list as adapters are enabled — your integration code doesn't change, you just select a different model id. Calling a registered model whose engine isn't enabled yet returns 501 engine_not_available. If a request omits model, the project's default model is used.

POST /v1/chat/completions — the OpenAI chat-completions shape. Minimal request:

{
  "model": "claude-opus-4-8",
  "messages": [
    {"role": "system", "content": "Answer in one sentence."},
    {"role": "user",   "content": "What is Hailey?"}
  ]
}

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "claude-opus-4-8",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "…" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 123, "completion_tokens": 45, "total_tokens": 168 }
}

Send the full messages history each call, exactly as with OpenAI — prior user/assistant turns are treated as conversation context. system messages are appended to the project's own system prompt (project instructions always apply first).

Image input

A user message may carry images using the OpenAI content-array form. Send each image as a base64 data: URI in an image_url part:

{
  "model": "claude-opus-4-8",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What does the label on this jar say?"},
      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQ…"}}
    ]
  }]
}

JPEG, PNG, GIF and WebP; up to 5 MB per image, 8 images and 20 MB per request, 8000 px per side. The type is read from the image itself, not from the URI. Remote http(s) image URLs are not fetched — encode the image and send it. Images work with streaming and with response_format, and may sit in any user turn of the history. An image that cannot be accepted is rejected with a 400; it is never silently dropped.

Set "stream": true to receive server-sent events of chat.completion.chunk objects, terminated by data: [DONE] — the standard OpenAI streaming contract, so SDK streaming helpers work unchanged. The final chunk carries usage.

stream = client.chat.completions.create(model="…", messages=[…], stream=True)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

A plain gateway call is stateless: it runs in a fresh, empty sandbox. A project gives your calls durable context — the gateway equivalent of running inside your project directory.

Create and manage projects at /settings/projects. Bind one to a key as its default, or select per request with hailey.project. Keys without a project use an auto-provisioned personal default project. A key can only reach projects owned by the same account.

Workspace modes

Calls run in parallel by default — including calls on the same key, project, and account. Fire as many concurrent requests as you need; nothing on the server queues them. Sequential execution is opt-in: pass "hailey": { "params": { "serial": true } } and calls to that project queue and wait their turn — each request blocks until the one ahead of it finishes, then runs. You only see 409 project_busy if a call waits longer than the server's queue cap (minutes) — an exceptional case, not the norm.

Conversations (shared mode)

In shared mode you may pass a conversation id of your choosing. The gateway maps it to a persistent engine session and resumes it on every call with the same id — server-side memory without re-sending history:

"hailey": { "workspace": "shared", "conversation": "onboarding-7c2" }

Hailey-specific options ride in an optional hailey object in the request body (use extra_body in the OpenAI SDKs). Clients that can't add body fields can send the equivalent headers.

{
  "model": "claude-opus-4-8",
  "messages": [ … ],
  "hailey": {
    "project":      "birthday-gold",   // project slug or id (default: the key's project)
    "workspace":    "shared",          // 'conversation' (default) | 'shared'
    "conversation": "onboard-7c2",     // shared mode only: resume this session
    "params":       { "max_turns": 8 },// per-call engine parameter overrides
    "retain_days":  -1                 // -1 = keep no transcript; 1–365 = delete after N days
  }
}

X-Hailey-Project: birthday-gold
X-Hailey-Workspace: shared
X-Hailey-Conversation: onboard-7c2
X-Hailey-Retain-Days: -1

client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Summarize the seed data."}],
    extra_body={"hailey": {"project": "birthday-gold"}},
)

An action is a task Hailey defines once and every site calls by name: the prompt, the output schema, the model and any scoring live in Hailey, not in your code. Fix or improve it once and every caller gets the change. An action must be granted to your account; one you can't use answers 404 action_not_found, the same as one that doesn't exist.

curl https://ask.hailey.io/v1/actions -H "Authorization: Bearer $HAILEY_API_KEY"            # what you may call
curl https://ask.hailey.io/v1/actions/kyc-verify -H "Authorization: Bearer $HAILEY_API_KEY" # its inputs + images
curl https://ask.hailey.io/v1/actions/kyc-verify -H "Authorization: Bearer $HAILEY_API_KEY" \
  -H "Content-Type: application/json" -d '{
    "inputs": { "name_on_account": "Jane Doe", "postal_code": "80202", "challenge": "Give a thumbs-up next to your face" },
    "images": { "id_front": "data:image/jpeg;base64,…", "id_back": "data:image/jpeg;base64,…", "selfie": "data:image/jpeg;base64,…" }
  }'

{
  "object": "action.result", "id": "act_…", "action": "kyc-verify", "version": 1, "model": "claude-opus-4-8",
  "verdict": "review",                        // pass | review | fail — act on this
  "score": 76,                                // 0–100, in the verdict's band: pass 90–100, review 31–89, fail 0–30
  "components": { "document": 100, "name": 100, "face": 30, "liveness": 100 },
  "reasons": [ { "code": "face_not_assessed", "severity": "review", "message": "The automatic face comparison was not made." } ],
  "address_match": "match",                   // match | different | unread | not_checked — never decisive
  "extracted": { "name_on_id": "…", "expires_on": "2030-01-01", "document_number_last4": "1234", … },
  "checks": { … the model's raw answer … },
  "retention": "none",                       // standard | none | Nd — see retain_days
  "usage": { "prompt_tokens": 15469, "completion_tokens": 844, "total_tokens": 16313 }
}

Parameters resolve in three layers: project defaults → per-request hailey.params → standard OpenAI top-level fields. Support depends on the engine; unsupported parameters are accepted and ignored, never fatal.

Errors use the OpenAI error envelope:

{ "error": { "type": "authentication_error", "message": "Invalid API key.", "code": null } }