Quickstart

This walks through one authenticated request end to end. It assumes an administrator has created your tenant and given you an API key beginning rdk_.

1. Know your base URL

Every request goes to the Gateway. There is no per-service host.

https://riddlerai.io:4443

On a local development stack this is https://localhost:4443, which uses a self-signed certificate — pass -k to curl, or trust the certificate, while developing.

2. Check you can reach it

The health endpoint needs no credentials, so it isolates connectivity problems from authentication problems.

curl https://riddlerai.io:4443/health

3. Confirm your key works

Send your key in the X-API-Key header:

curl https://riddlerai.io:4443/api/os/workspaces \
  -H "X-API-Key: rdk_your_key_here"

Authorization: Bearer rdk_your_key_here works identically, which is convenient if your HTTP client makes bearer tokens easier to configure than custom headers.

A 401 here means the key was rejected — an unrecognised or revoked key gives the same 401 as no key at all. A 200 returns your tenant’s workspaces, which confirms both that the key is valid and which tenant it resolved to.

4. Run an inference

curl https://riddlerai.io:4443/api/llm/v1/chat/completions \
  -H "X-API-Key: rdk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      { "role": "user", "content": "Explain vector search in two sentences." }
    ],
    "max_tokens": 256
  }'

"auto" lets the platform pick the tenant’s configured default, which is the right choice unless you need a specific model — model availability varies by tenant and by which compute nodes are connected. A stock deployment resolves it to llama3.2:1b. Call /api/llm/v1/models to see what is actually available to you, and pass one of those ids to pin a model.

The response is OpenAI-shaped, with three RiddlerAI additions:

{
  "id": "riddler-20260728065456-b",
  "object": "chat.completion",
  "model": "llama3.2:1b",
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" }
  ],
  "usage": { "prompt_tokens": 106, "completion_tokens": 2, "total_tokens": 108 },
  "rag_snippets": null,
  "rag_active": false,
  "rag_status": "inactive"
}

The rag_* fields describe whether the answer was grounded in your own documents. They stay inactive until you ask for grounding — see Streaming and grounded chat.

Only messages is strictly required. model defaults to "auto", max_tokens defaults to 1024 with a ceiling of 8192, and temperature defaults to 0.7.

5. Stream the response

Set "stream": true on the same endpoint to receive tokens as they are generated:

curl -N https://riddlerai.io:4443/api/llm/v1/chat/completions \
  -H "X-API-Key: rdk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "model": "auto", "messages": [{ "role": "user", "content": "Count to three." }], "stream": true }'

Streaming and grounded chat covers the frame format.

6. Handle the failures you will actually hit

Three are worth handling before you go further than a prototype:

• 400 — the request was rejected. Read the body: validation failures and application errors use different shapes, so branch on the status code rather than the body.
• 429 — you are being rate limited. Back off exponentially.
• 503 — a downstream service is briefly unavailable, or a required model is not loaded. Retry with backoff.

Errors and rate limits covers the full set, including the two error shapes.

Next

• Authentication — API keys versus user tokens, and when to use each
• Streaming and grounded chat — SSE frames, conversations, and RAG
• Tenants and isolation — how the platform decides what your key can see
• API reference — every endpoint, with a console to try them against your own tenant