API reference

Base URL: https://api.renbase.ai. Every endpoint takes Authorization: Bearer <credential> and returns JSON, except /v1/ask and the event streams, which return Server-Sent Events.

Authentication

Two kinds of credential, both resolved live — revoking one takes effect immediately.

API keys (kb_live_…) are for services and agents. An admin issues them in Renbase Studio or through /v1/keys.

Session tokens are for people. A member requests a one-time code by email and exchanges it for a token:

curl -X POST $RENBASE_API/auth/request-otp \
  -H 'content-type: application/json' -d '{"email": "[email protected]"}'

curl -X POST $RENBASE_API/auth/verify-otp \
  -H 'content-type: application/json' -d '{"email": "[email protected]", "code": "123456"}'

Codes expire, and they're invalidated after a few failed attempts. Roles are admin (governance, keys, members, deletion) and read (asking and browsing).

Asking

POST /v1/ask

Streams a cited answer over SSE. Consumes one credit.

{
  "query": "what is the return window?",
  "collection": "support",
  "filters": {"lang": "en"},
  "history": [{"role": "user", "content": "…"}]
}

Events in order: sources (what it will use), token (text as it's produced), done (resolved citations and whether it abstained). Follow-up questions are rewritten using history, so "and for digital products?" works as a continuation.

POST /v1/search

Ranked passages without generation, when you want to build the answer yourself. Consumes one credit.

{ "query": "return window", "collection": "support", "filters": {"category": "policies"} }

Returns hits with scores, source and per-stage timings.

POST /v1/feedback

Records whether an answer was helpful. Unhelpful ones with a correction feed the refinement queue, and an admin can promote them into rules.

{ "answer_id": "…", "helpful": false, "comment": "the window is 30 days, not 14" }

Documents

Method	Path	Role	Description
POST	/v1/documents	member	Upload a document (multipart); returns a job
GET	/v1/documents	member	Paginated list, filterable by collection and text
GET	/v1/documents/{id}	member	Detail: collection, size, chunk count
GET	/v1/documents/{id}/chunks	member	How the document was split
DELETE	/v1/documents/{id}	admin	Remove the document and its content from answers
POST	/v1/documents/{id}/reindex	admin	Rebuild its search entries
GET	/v1/collections	member	Collections with document counts
GET	/v1/jobs · /v1/jobs/{id}	member	Processing queue
GET	/v1/jobs/events	member	SSE stream of job progress
POST	/v1/jobs/{id}/retry	admin	Requeue a failed job

Details in Documents.

Definitions

Method	Path	Role	Description
POST	/v1/context	admin	Create a definition (approve: true publishes it)
GET	/v1/context	admin	List; ?status=draft is the review queue
GET	/v1/context/{id}	admin	Detail with version history
PATCH	/v1/context/{id}	admin	Edit: creates a new approved version
DELETE	/v1/context/{id}	admin	Withdraw
POST	/v1/context/{id}/approve · /reject	admin	Review a draft
POST	/v1/context/import	admin	Import candidates; everything arrives as a draft
GET	/v1/context/resolve?q=	member	Deterministic resolution by name or alias (free)
GET	/v1/feedback	admin	Refinement queue
POST	/v1/feedback/{id}/promote	admin	Turn a correction into a rule

Details in Business definitions.

Organization

Method	Path	Role	Description
POST/GET/DELETE	/v1/keys	admin	Issue, list and revoke API keys
POST/GET/PATCH/DELETE	/v1/users	admin	Manage members and roles
GET	/v1/credits	member	Balance and plan (free, doesn't consume)
POST	/v1/billing/checkout	admin	Open a Stripe payment page: {"amount":50} or {"setup":true}
POST	/v1/billing/portal	admin	Stripe Customer Portal: subscription and invoices
GET/POST	/v1/billing/autorecharge	admin	Read or set auto top-up: {"threshold":200,"amount":50}
GET	/v1/usage	member	Spending history by day and endpoint (?days=30)
POST	/mcp	member	MCP endpoint for agents — see AI agents

Credits and rate limits

Asking and searching consume one credit each. Reading, listing, resolving a definition and unfolding a source are free. Your plan defines the allowance and the period; the balance resets on the first request after the period ends.

GET /v1/credits is deliberately free and outside the rate limit, so a throttled or exhausted integration can always check where it stands. It reports credits left and the allotment your plan grants on renewal — both -1 when unlimited.

GET /v1/usage answers the other question — where the credits went. It returns the last 30 days by default (?days= up to 365), broken down two ways: a day-by-day series with no gaps, so a day with no traffic reports zero rather than going missing, and a per-endpoint total sorted by spend. Both are free and outside the rate limit too: checking the bill shouldn't cost you.

The endpoint breakdown names the tool as well as the route, so an agent's traffic (mcp:ask, mcp:search_context) is told apart from the panel's (/v1/ask, /v1/search). All MCP tools share one URL, so without that they'd all read as "MCP", which answers nothing.

There are two ways to add credits. A top-up is a one-off purchase that adds to whatever balance you still have. A subscription sets your plan and refills its allowance every period. Both return a URL from /v1/billing/checkout — you finish the payment on Stripe, and the balance moves when Stripe confirms it, usually a second or two after you come back.

The allowance is a floor, never a ceiling: renewing tops you back up to it if you're below, and leaves a bigger balance alone. So credits you bought stay yours — they survive the renewal, and cancelling a subscription changes your plan without touching them.

You always say how much you want to pay, never how many credits you want: pass amount, and your rate is set by the last pack you pass, so $200 buys credits at the same rate as the $100 pack. The published packs are just convenient amounts — any figure between the smallest pack and the cap works the same way. The conversion happens on the server.

Auto top-up keeps an agent from stranding mid-run: set a threshold and an amount, and we charge that amount when the balance drops below it, using the card left behind by an earlier payment. The amount is whatever you choose — a pack or any figure the checkout accepts — and the credits it buys are worked out at the rate in force when it fires, so a price cut reaches you without reconfiguring anything. Charges happen without you present, so a bank that demands authentication (SCA in Europe) will decline them — when that happens the top-up doesn't go through and you'll need to pay once by hand. Recharges are spaced apart, so a runaway agent can't trigger a burst of them.

Rate limits apply per organization, as requests per minute with a small burst. Exceeding them returns 429 with Retry-After, and a throttled request never spends a credit.

Errors

Code	Meaning
400	Malformed request — check the body against the examples
401	Missing, invalid or revoked credential
403	Valid credential without the required role (most often: an admin action with a read token)
404	The resource doesn't exist, or belongs to another organization
413	Document over the size limit
429	Rate limit exceeded; retry after Retry-After
402	No credits left: top up or upgrade your plan

Note that 404 covers content from another organization: rather than telling you that something exists but isn't yours, it isn't there at all.

An abstention is not an error. /v1/ask returns 200 with abstained: true and an explanation — the system working as intended.