HolaOra API — v1

Every request includes a Bearer token in the Authorization header:

Authorization: Bearer ho_live_xxxxxxxxxxxxxxxxxxxxxxxx

Hit /v1/usage first — it has no side effects, no LLM cost, and confirms the key works:

curl -s https://holaora.com/api/v1/usage \
  -H "Authorization: Bearer ho_live_YOUR_KEY"

You should get JSON back with your user_id, organization_id, plan, limits and today's quota.

• POST /api/v1/chat — send a message, get the assistant's reply
• GET /api/v1/usage — read your plan, limits, today's message count
• GET /api/v1/documents — list documents in this key's workspace

Each key is bound to one workspace at creation. Calls only see documents and quota counts from that workspace. To act on a different workspace, generate a separate key from the dropdown in the create form.

• API access requires the Scale plan (€79/mo). See pricing or sign up to mint a key.
• Scale has unlimited daily messages — no per-key rate limit beyond that.
• If we ever return 429, back off and retry with exponential backoff.

POST /api/v1/chat
Authorization: Bearer ho_live_YOUR_KEY
Content-Type: application/json

Body:

{
  "messages": [
    { "role": "user", "content": "How do I cancel my subscription?" }
  ],
  "model": "openai/gpt-4o-mini"   // optional; defaults to your account model
}

Curl:

curl -X POST https://holaora.com/api/v1/chat \
  -H "Authorization: Bearer ho_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"What does HolaOra do?"}]}'

Plain text — the assistant's reply, end to end. Currently buffered, not server-sent-events streaming. Status 200 on success.

HolaOra is an AI customer-support assistant that answers questions
from your knowledge base across chat, embed widget, WhatsApp, and API.

• 401 — missing, malformed, revoked, or expired key
• 429 — daily message cap (Scale doesn't hit this)
• 502 — upstream LLM error; retry once with backoff

• Each call counts as one message in your daily quota.
• Conversation history is your responsibility — pass full messages[] on every call. The endpoint is stateless.
• RAG retrieval against your knowledge base happens automatically. No need to pass document context.

GET /api/v1/usage
Authorization: Bearer ho_live_YOUR_KEY

Curl:

curl -s https://holaora.com/api/v1/usage \
  -H "Authorization: Bearer ho_live_YOUR_KEY"

{
  "user_id": "afa1a41a-fbd3-...",
  "organization_id": "6570d2cc-6380-...",
  "plan": "scale",
  "limits": {
    "maxKnowledgeBases": null,
    "dailyMessages": null,
    "maxTeamMembers": 10,
    "storageBytes": null
  },
  "usage": {
    "dailyMessagesUsed": 6,
    "dailyMessagesRemaining": null
  }
}

null in limits means unlimited. dailyMessagesUsed is scoped to the key's bound workspace, not all your activity.

• Pre-flight before a batch job — check remaining quota.
• Build your own usage dashboard.
• Detect when a customer's plan changed (poll the plan field).

GET /api/v1/documents?limit=50&offset=0
Authorization: Bearer ho_live_YOUR_KEY

Query parameters:

• limit — default 50, max 200
• offset — default 0, for pagination

Curl:

curl -s "https://holaora.com/api/v1/documents?limit=10" \
  -H "Authorization: Bearer ho_live_YOUR_KEY"

Only documents in the workspace this key is bound to are returned. Documents in your other workspaces are invisible to this key. To list those, mint a key against the other workspace from the API keys page.

• Read-only for v1 — no upload, update, or delete via API yet.
• Use the in-product UI or the embed widget admin to manage documents.