API first success

You can reach a grounded answer without using the dashboard after setup. This path is for teams that want agent behavior behind their own scripts, jobs, or UI. A personal token uploads the workspace document; a role-free REST agent credential talks to one agent.

Before you start

Every call below needs a Radioso host to talk to. Use the hosted EU API at https://api.radioso.ai, the hosted US API at https://api-us.radioso.ai, or your own origin if you’re self-hosting — start the stack first with Run locally in 5 minutes, then swap in http://localhost:8080. Pick one host and stay on it for every step below: an API credential only works against the instance that issued it.

The examples on this page call https://api.radioso.ai.

The happy path

From nothing to a grounded answer follows this sequence:

1. check whether registration is available
2. create or access an account
3. establish a session
4. issue a personal API credential
5. upload one document
6. create a REST credential for the chosen agent
7. ask one agent question whose answer should obviously come from that document

One concrete example

Say you upload a document that reads:

Refunds are available within 14 days of purchase with proof of payment.

A good first API test is then:

• upload that exact text
• wait for processing to complete
• ask, What is the refund window?

If the system is working, the answer comes back grounded in that document rather than sounding generic. That contrast, your text versus a plausible guess, is the thing you’re checking for.

Register

curl -sS https://api.radioso.ai/api/v1/auth/registration

The response is { "available": true } or { "available": false }. Open-source registration is available only until the first organization has been created. Later users join that organization by invitation. Enterprise Edition keeps registration available.

When registration is available:

curl -sS \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"verysecurepassword"}' \
  https://api.radioso.ai/api/v1/auth/register

Registration returns bootstrap data such as workspaceId and a requiresEmailVerification boolean. Production returns true, sends a verification email, and waits for verification before login. The development stack returns false and establishes the session in the registration response.

If the user already exists, log in and save the session cookie:

curl -sS -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"verysecurepassword"}' \
  https://api.radioso.ai/api/v1/auth/login

Issue a personal API credential

personal_expiry="$(node -p 'new Date(Date.now() + 30 * 86400000).toISOString()')"
curl -sS -b cookies.txt -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Radioso-CSRF: 1' \
  -H 'X-Workspace-Id: <workspace-id>' \
  -d "{\"label\":\"First API client\",\"roleCeiling\":\"member\",\"expiresAt\":\"${personal_expiry}\"}" \
  https://api.radioso.ai/api/v1/account/workspaces/<workspace-id>/api-access/personal-tokens

If you need to list workspaces first:

curl -sS -b cookies.txt \
  https://api.radioso.ai/api/v1/workspace

The issue response contains safe metadata and the one-time secret:

{"credential":{"id":"...","prefix":"radioso_pat_ab12"},"secret":"radioso_pat_..."}

The dashboard provides the same personal-token flow from the workspace API access controls. Copy the secret into your client’s secret manager before acknowledging it; later inventory responses cannot recover it.

If the credential is exposed, rotate or revoke it from API access settings. Use a service account instead when the client should keep working independently of your membership.

Upload one document

You can use the SDK:

import { createRadiosoClient } from '@radioso/typescript-sdk'
 
const client = createRadiosoClient({
  apiToken: process.env.RADIOSO_API_TOKEN!,
  // baseUrl defaults to https://api.radioso.ai; set it explicitly for
  // https://api-us.radioso.ai or a self-hosted origin like http://localhost:8080
})
 
await client.documents.create({
  title: 'Refund policy',
  content: 'Refunds are available within 14 days of purchase with proof of payment.',
  source: { kind: 'website', url: 'https://example.com/docs' },
})

When the source of truth is a file, import it instead:

import { readFile } from 'node:fs/promises'
 
const file = await readFile('./refund-policy.pdf')
 
await client.documents.importFile({
  file,
  filename: 'refund-policy.pdf',
  title: 'Refund policy',
  mimeType: 'application/pdf',
})

You can also use the raw HTTP document routes directly, including the multipart POST /api/v1/document/import path.

Create a REST agent credential

List the workspace’s agents with the personal token and choose the one the integration should use:

curl -sS https://api.radioso.ai/api/v1/agents \
  -H "Authorization: Bearer $RADIOSO_API_TOKEN"

Then issue a credential through the signed-in session. The session must have permission to manage that agent.

agent_expiry="$(node -p 'new Date(Date.now() + 30 * 86400000).toISOString()')"
curl -sS -b cookies.txt -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Radioso-CSRF: 1' \
  -H 'X-Workspace-Id: <workspace-id>' \
  -d "{\"audience\":\"rest\",\"label\":\"First chat client\",\"expiresAt\":\"${agent_expiry}\"}" \
  https://api.radioso.ai/api/v1/agents/<agent-id>/channel-credentials

Store this response’s secret separately as RADIOSO_AGENT_API_TOKEN. It is bound to the chosen agent and does not carry the personal token’s workspace role.

Ask one question that should have an obvious answer

curl -sS -X POST https://api.radioso.ai/api/v1/agents/<agent-id>/chat \
  -H "Authorization: Bearer $RADIOSO_AGENT_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"message":"What is the refund window?","stream":false}'

The response is the grounded answer plus the citations that support it — here is the exact shape:

{
  "conversationId": "5b1b6e9e-2b0a-4f1d-9c4a-7e8f2a6c9d31",
  "assistantMessageId": "8f2c5a3e-9d1b-4a7c-b6e2-1f4d8c0a5b93",
  "agentId": "3a9d7c5e-1b2f-4e8a-9c6d-5f0e3a7b2c14",
  "agentName": "Support",
  "answer": "Refunds are available within 14 days of purchase with proof of payment.",
  "citations": [
    {
      "documentId": "c1d2e3f4-5678-4abc-9def-0123456789ab",
      "chunkId": "d2e3f4a5-6789-4bcd-8ef0-123456789abc",
      "title": "Refund policy",
      "sourceUrl": "https://example.com/docs"
    }
  ],
  "answerSegments": [
    {
      "text": "Refunds are available within 14 days of purchase with proof of payment.",
      "citationIndices": [0]
    }
  ],
  "suggestions": []
}

citations[].sourceUrl only shows up when the source document carries one — the document you uploaded above does, because you passed source: { kind: "website", url: "https://example.com/docs" }. A plain inline document without a source still cites documentId and title. (The full response can also carry ownership and debug fields; see the API Reference for the complete schema.)

What success looks like

• you can establish a session and issue a personal token
• the document is accepted and processed
• the answer is about your uploaded document, not a generic policy guess
• if citations are enabled for the workspace, the answer points back to the supporting content

Common failure mode

If upload works but chat doesn’t, one of these is usually true:

• document processing is still running
• the backend does not have a valid provider key
• the session cookie was not saved by the client

What to do next

• If the API behavior looks right, continue with TypeScript SDK getting started.
• If the answer quality is weak, review Document upload and Agents and skills.