Developer Docs
Integrate with Raindex capabilities.
Applications use the REST API and compatible agents use MCP. Both reach the same product-owned capabilities as the Raindex UI and Agent, with the same Account scope, confirmation and receipts. This guide covers credentials, request rules and refusal behavior; the references document the current interface contracts.
Getting started
Create a key, verify it, then choose REST or MCP.
Start →API reference
Endpoints, parameters and schemas from the live OpenAPI contract.
Open reference →MCP
Client configuration and the shared workflow tool schemas.
Open MCP →Getting started
- Sign in and open the Developer Console for the Account your integration will act in. Create an API key there. The full secret is shown once.
- Store the secret in your secret manager or client secret store. Never put it in a URL, a repository or a ticket.
- Verify the key with the authenticated identity endpoint before building a larger workflow.
- Choose an interface: the REST API for applications, or MCP for compatible agents.
curl https://raindex-backend.onrender.com/v1/auth/whoami \
-H "Authorization: Bearer raindex_your_key_here"Authentication
Every scoped request carries Authorization: Bearer …. An API key is bound to one Account when it is created, and the server resolves that Account from the key. A caller-supplied Account header cannot move a key into another Account. First-party sessions send the active Account inX-Account-ID.
# API key: the key resolves its Account on the server.
Authorization: Bearer raindex_your_key_here
# First-party session (JWT): send the active Account explicitly.
Authorization: Bearer <session-token>
X-Account-ID: <account-id>API key lifecycle
- Shown once
- The secret is returned only at creation. Raindex keeps a hash and a display prefix, so a lost secret cannot be recovered.
- Rotation
- Create a new key, move your client to it, then revoke the old key. There is no in-place reset.
- Revocation
- A revoked key fails immediately and cannot be restored. Its audit identity remains.
- Management
- Keys are created, inspected and revoked only in the signed-in Developer Console for their Account.
Account scope
Every private object belongs to exactly one Account. Object identifiers resolve only inside the calling Account; an object from another Account behaves as not found rather than forbidden, so identifiers cannot be used to probe other Accounts. The user who created a key is recorded as the actor for audit, but the Account, not the user, is the ownership boundary.
Documented is not the same as available
These docs describe interface contracts. They do not claim that a particular Account can invoke a given endpoint or tool. For each request Raindex resolves:
- the key's lifecycle and its Account;
- the Account's current capabilities and entitlement;
- owner readiness and authorization for the exact objects involved;
- any confirmation and freshness requirement of the operation; and
- platform availability controls.
The authoritative Account-specific view is authenticated discovery: MCP tools/list, or Capabilities in the Developer Console. Counts shown in references are derived from the live registry when the page loads and are not a fixed product promise.
Governed actions and receipts
Reads are bounded and Account-scoped. Changes go through the owning product workflow, never through direct table writes or arbitrary SQL.
- Preview is not Apply. Where an operation requires review, request a fresh Preview, then apply it with the confirmation the Preview returns.
- A confirmation-required response is a real stopping point. Do not retry around it.
- HTTP success proves the request completed. It is not proof of a business effect. A queued job must be followed to its terminal state, and the effect should be verified through the returned receipt and resulting state.
- Retry an uncertain network outcome with the same request identity and unchanged input to recover the original receipt.
Errors and refusals
Refusals are explicit and independent. Handle each class distinctly and read the response detail.
| Refusal | Meaning | What to do |
|---|---|---|
| Unauthenticated (401) | Missing, malformed, revoked or unknown credential. | Check the header and the key's status in the Developer Console. |
| Unauthorized or unentitled | The Account or caller lacks the role or capability for this operation. | Confirm Account capabilities; do not switch credentials to force access. |
| Not found (404) | The object does not exist in this Account, including objects owned by another Account. | Verify the exact identifier and Account. |
| Conflict | A pinned version, hash or input no longer matches, or a request identity was reused with changed input. | Rediscover deliberately. Never substitute the latest version silently. |
| Validation | The request body or parameters do not satisfy the declared schema or limits. | Correct the input; oversized batches refuse as a whole. |
| Confirmation required | The operation needs a fresh Preview and explicit confirmation. | Stop, review and confirm through the supported path. |
Versioning and deprecation
- Pin exact identities: published versions, content hashes and revision IDs. Raindex does not replace a requested version with the latest one.
- Shared workflow tools publish a workflow version and input and output schema hashes. Treat a hash change as a contract change.
- Public Developer Docs omit interfaces already designated for retirement. Current compatibility routes can remain documented until the replacement external contract is complete.
- Some Network capabilities retain
/v1/enginecompatibility paths during the V1 route cutover. Use the exact documented path; do not infer product ownership from the route prefix. - The references read the live contracts each time they load, so they reflect what is deployed rather than a snapshot.
Examples
Examples use synthetic facts and placeholders. They are never defaults for your data and never contain real credentials or Account identifiers.
Start with the current interface
Verify the key with /v1/auth/whoami, inspect the Account's available capabilities, then choose an exact documented Source, Network or WorkSpace contract for the decision. Keep source revisions, policy versions and request identities exact. Rulebooks select from existing options; the replacement external evaluation contract will be documented when it is ready.