StudioX API User Guide (GraphQL)

Call the StudioX GraphQL API with your personal API key: people and roles, knowledge sources, streaming chat, the API workbench, every error code.

For developers integrating with StudioX through its GraphQL API. For a REST API with scoped tokens, see the StudioX Core API.

Updated Oct 19, 2026


title: "StudioX API" subtitle: "User Guide" cover: true

Contents

Section Page
1. StudioX API — Introduction ·
    The two surfaces ·
    Four things to know before you write code ·
    What you need ·
2. Getting Started ·
    Generate your API key ·
    Set your base URL ·
    Your first call ·
    Your first chat ·
    Where to go next ·
3. Authentication ·
    Getting a key ·
    Checking that a key works ·
    What a key can do ·
    Quotas ·
    Key lifecycle ·
    Key hygiene ·
4. Conventions and Errors ·
    The response envelope ·
    HTTP 200 does not mean success ·
    Two different kinds of failure ·
    Status codes ·
    Asynchronous operations ·
    Pagination ·
    Identifiers ·
    Versioning ·
5. Administration ·
    Health check ·
    Get the current user ·
    Get the AI engine version ·
    List users ·
    Create a user ·
    Update a user ·
    List businesses ·
    Delete a user ·
    Worked example: provision a user ·
6. Knowledge Base ·
    Add a source ·
    Tracking ingestion ·
    List sources ·
    Labels ·
    Delete a source ·
    Errors ·
7. Chat API ·
    Two modes: choose before you build ·
    Authentication failures do not return 401 ·
    Access modes ·
    Request ·
    Response ·
    Parsing the stream ·
    Conversation flow ·
    Examples ·
    Streaming mode (real SSE) ·
    Error handling ·
8. API Workbench ·
    Layout ·
    Reading the schema ·
    A first query ·
    A query with variables ·
    Authentication in the Workbench ·
    Workflow ·
9. Data source types ·
    Query the live list ·
    Common types ·
    Naming ·
    Conversation-scoped types ·
    Linked-source types ·
10. Error codes ·
    Success ·
    Authentication and authorization ·
    Quotas ·
    Not found ·
    Validation ·
    Server ·
    Chat API ·
11. Roles and permissions ·
    Primary roles ·
    Who can call what ·
    Bot operations are gated twice ·
    Designing an integration ·

The StudioX APIs let you integrate StudioX into your own applications and workflows: administer users, manage a bot's knowledge base, and hold conversations with a bot from your own code.

The information contained herein is confidential. This document may contain proprietary, privileged, and/or confidential information and is intended only for the use of the addressee(s) named above. Unauthorized review, use, disclosure, or distribution of this document, or any part of it, is strictly prohibited.


The two surfaces

Platform API Chat API
URL <BASE_URL>/api/graphql/ <BASE_URL>/api/chatbot/chat/
Style GraphQL JSON request, streamed response
Header Authorization: <YOUR_API_KEY> personal-api-key: <YOUR_API_KEY>
Method POST POST
For Users, businesses, knowledge base, platform Conversations with a bot

The same API key works on both. Only the header name differs, and getting it wrong on the Chat API fails silently — this is the most common integration mistake, and Authentication opens with it.

<BASE_URL> is your installation

Every URL in this guide begins with <BASE_URL>. Substitute the address of the StudioX installation you are calling:

Deployment BASE_URL
StudioX cloud https://www.studiox-ai.com
A partner or private installation Whatever address you reach StudioX at, for example https://studiox.example.com

Every path in this guide — /api/graphql/, /api/chatbot/chat/, /apidocs — is the same on every installation. Only the host differs.

The shell examples assume you have exported it:

export BASE_URL="https://www.studiox-ai.com"   # or your own installation

If you are unsure which address to use, it is the one you sign in to StudioX at.


Four things to know before you write code

These are the behaviours that surprise people. Each is covered in full later.

1. HTTP 200 does not mean success. A GraphQL operation that fails for auth, permission or quota reasons still returns HTTP 200. The real result is response.status inside the body. → Conventions and Errors

2. The Chat API has two response protocols. ?streaming=true gives you standard SSE with real HTTP status codes. Without it, you get a different framing that standard SSE clients cannot parse, and an invalid key produces HTTP 200 with the error delivered token-by-token as though it were the answer. New integrations should use ?streaming=true. → Chat API

3. Your key is not a superuser. It carries its owner's role and business scope, and a bot that restricts API access can refuse a key whose owner can use that bot in the dashboard. → Authentication

4. Uploading a document does not make it searchable. Ingestion is asynchronous; a 200 means queued. → Knowledge Base


What you need

  • A StudioX API key — Getting Started
  • An HTTP client — curl, Postman, Insomnia, or your language's HTTP library
  • For the Chat API, a client that can read a stream and does not buffer the whole response

The examples use curl and Python. Nothing depends on a StudioX SDK.

Generate your API key

1. Open the Admin area. Sign in to StudioX and click Admin in the top right.

!StudioX home with the Admin menu highlighted

2. Open Profile.

!Administration page with the Profile card highlighted

3. Find the StudioX API Key panel.

!Profile page with the StudioX API Key panel highlighted

4. Click Generate New Key and confirm.

!Generate New Key confirmation dialog

Copy the key immediately and store it somewhere safe. Generating a new key replaces the previous one — anything still using the old key stops working.

A key belongs to a person, and carries that person's role and business access. For an integration, create a dedicated service account with the minimum role that works rather than using your own key. It survives staff changes and limits the blast radius.

See Key hygiene.


Set your base URL

The examples in this guide are written against your installation, not a fixed address. Export it once and every curl below works as written:

export BASE_URL="https://www.studiox-ai.com"   # the StudioX cloud
# export BASE_URL="https://studiox.example.com"   # a partner installation

It is the address you sign in to StudioX at. The paths after it are identical on every installation.


Your first call

currentUser is the right first request: it proves the key works and returns the business ID most other operations need.

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ currentUser { user { id name email primaryBusiness role } response { status message code } } }"}'

A working key returns:

{
  "data": {
    "currentUser": {
      "user": {
        "id": "b7c91f4a23d56789ef012345",
        "name": "Alex Johnson",
        "email": "alex.johnson@example.com",
        "primaryBusiness": "7d6e5c4b3a2109f8edc65432",
        "role": "business-admin"
      },
      "response": {
        "status": 200,
        "message": "Current user query has been successful",
        "code": "CURRENT_USER_QUERY_SUCCESSFUL"
      }
    }
  }
}

Keep user.primaryBusiness — you will need it throughout Administration.

If it did not work

A bad key returns HTTP 200 with the failure in the body:

{"data":{"currentUser":{"user":null,
 "response":{"status":401,"message":"Unauthorized","code":"UNAUTHORIZED"}}}}

Check that:

  • the header is Authorization, with no Bearer prefix
  • the key has not been replaced by a newer one, or revoked
  • you are reading response.status, not the HTTP status code

Do not test a key against the health check — it is unauthenticated and returns 200 regardless. See Checking that a key works.


Your first chat

Different endpoint, different header.

curl -N -X POST "$BASE_URL/api/chatbot/chat/" \
  -H "Content-Type: application/json" \
  -H "personal-api-key: <YOUR_API_KEY>" \
  -d '{
    "messages": [
      { "role": "assistant", "content": "Hello! How can I help you today?" },
      { "role": "user", "content": "What information is available in the documents?" }
    ],
    "data": { "botUrl": "$BASE_URL/bot" }
  }'

The response streams as prefixed frames:

2:[{"processType":"conversationIdCreated","processData":"68e94c6613b15f5ebb35d11a","processId":1}]
0:"I'm"
0:" here"
0:" to"
0:" help"
0:"!"

Concatenate the 0: payloads for the answer. curl -N disables buffering so you see tokens as they arrive.

Replace botUrl with your own bot's URL — copy it from Dashboard → AI Assistants. Then read Chat API before writing a real client: this endpoint reports authentication failures as HTTP 200 with the error streamed as content, and the stream is not SSE despite its content type.


Where to go next

StudioX exposes two API surfaces, and they do not use the same authentication header. Sending the right key with the wrong header name is the single most common integration failure, and on the Chat API it fails silently.

Surface Base URL Header Method
Platform API (GraphQL) <BASE_URL>/api/graphql/ Authorization: <YOUR_API_KEY> POST
Chat API (streaming) <BASE_URL>/api/chatbot/chat/ personal-api-key: <YOUR_API_KEY> POST

The same API key works on both surfaces. Only the header name differs.

The Chat API ignores Authorization entirely. It reads personal-api-key and nothing else. If you send your key as Authorization to /api/chatbot/chat/, the request is treated as unauthenticated — it is not rejected. Against a bot that allows anonymous access the call appears to succeed, and it keeps appearing to succeed until someone re-enables sign-in on that bot. See Chat API → Authentication failures.

Custom headers are dropped

POST /api/graphql/ is served by a proxy that rebuilds the request headers as an allow-list before forwarding to the API. Only these survive:

Header Purpose
Authorization Your API key
Content-Type application/json, or multipart/form-data for uploads
x-app-url Calling application context
x-guest-token Anonymous visitor's conversation ownership

Anything else you set — a custom auth header, a correlation ID, a tenant hint — is silently discarded and never reaches the API. Put per-request context in the GraphQL variables, not in headers.

There is no Bearer prefix on either surface. Send the raw key:

Authorization: sx_live_abc123...        ← correct
Authorization: Bearer sx_live_abc123... ← wrong

Getting a key

See Getting Started → Generate your API key for the walkthrough with screenshots. In short: Admin → Profile → StudioX API Key → Generate New Key.

A key belongs to a user, not to a business or an application. Everything in the next section follows from that.


Checking that a key works

Use currentUser. It is the cheapest call that actually exercises authentication, and it echoes back the identity and business scope the key resolves to — which is what you need for almost every other call anyway.

curl -s -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ currentUser { user { id name email primaryBusiness role } response { status message code } } }"}'

A working key returns response.status: 200 and a populated user object.

Do not use the health check to validate a key. getSystemHealthCheck and GET /api/healthCheck/ are unauthenticated — they return 200 with no header at all, and they return exactly the same 200 for a valid key, a revoked key, a typo'd key and no key. They tell you the platform is up. They tell you nothing about your credentials.

An unauthenticated or invalid key on a protected query looks like this — note that HTTP status is still 200:

{
  "data": {
    "getAIEngineVersion": {
      "aiEngineversion": null,
      "aiEngineDeployedDate": null,
      "response": { "status": 401, "message": "Unauthorized", "code": "UNAUTHORIZED" }
    }
  }
}

This is the standard StudioX response envelope. Read Conventions and Errors before you write any error handling.


What a key can do

An API key is not a superuser credential. It carries its owner's identity, and every authorization decision is made against that user:

  • Primary role — one of user, business-support, business-admin, business-super-admin.
  • Business scope — the businesses the user is linked to. Most queries take a linkedBusinessId or equivalent and will refuse a business the user is not a member of (UNAUTHORIZED_BUSINESS_ACCESS, BUSINESS_NOT_FOUND).

A key owned by a user-role account calling addUserToBusiness gets NOT_AUTHORIZED, not a created user. If you are provisioning users over the API, the key must belong to an account with business-admin or above.

See Roles and permissions for the per-operation matrix.

Bots carry their own API access list

A bot-scoped request made with an API key is checked against that bot's API access list. A request made from a signed-in browser session is not. Each bot carries a botAPIsAccess.usersRestriction setting that decides what the list means:

usersRestriction An API key may call the bot's APIs if
businessUsers (default) Its owner belongs to the bot's business
Restricted Its owner's email is on the bot's userEmails, or in one of its teams

On the default setting this changes nothing — belonging to the bot's business is already required. It matters when a bot is set to restrict API access: the same person who can use that bot in the dashboard then gets API_ACCESS_DENIED from addKnowledgebaseSource or getKnowledgebaseLabels with their own key, because their email is not on the list.

If you get API_ACCESS_DENIED on a bot operation, the fix is in the bot's configuration, not in your key.


Quotas

Usage is governed by a per-user and per-business consumption budget. When a budget is exhausted the call fails with response.status: 400 and one of:

response.code Budget
TOKEN_LIMIT_EXCEEDED Tokens in a single request
MONTHLY_TOKEN_LIMIT_EXCEEDED Tokens consumed this calendar month
STORAGE_LIMIT_EXCEEDED Knowledge base storage, in GB
DOCS_LIMIT_EXCEEDED Number of documents in the business
PAGES_LIMIT_EXCEEDED Number of document pages in the business

The accompanying message is written for humans and states current usage against the ceiling — surface it to your users rather than rewriting it.

Each budget is set per user, or inherited from the business. The useBusinessTokenLimit / tokenLimit family of fields on Create user is where these are configured.

Retrying an exhausted quota will not clear it. Treat these five codes as terminal and escalate to an administrator.


Key lifecycle

Facts you will need for a security review:

Property Behaviour
Expiry Keys do not expire. A key is valid until it is replaced or revoked
Rotation Generating a new key immediately invalidates the previous one. Available in the UI and over the API — see Rotating a key programmatically
Revocation Immediate, and takes effect on the next request. An administrator can also revoke keys for selected users
Scope One key per user, carrying that user's role and business access
Transport HTTPS only
Audience The same key authenticates both surfaces

Because keys do not expire on their own, rotation is your responsibility. Put it on a schedule, and revoke immediately when a key may have been exposed or when its owner leaves.

Rotating a key programmatically

Three mutations act on the calling key's own account, so a service account can rotate its own credential without an administrator:

# Check a key. Purpose-built, and cheaper than currentUser.
curl -X POST $BASE_URL/api/graphql/ \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation VerifyPersonalApiKey($input: VerifyPersonalApiKeyInput!) { verifyPersonalApiKey(input: $input) { status message code } }",
    "variables": { "input": { "personalApiKey": "<YOUR_API_KEY>", "isCheckForBot": false } }
  }'

# Mint a replacement. The OLD KEY STOPS WORKING the moment this returns.
curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" -H "Content-Type: application/json" \
  -d '{"query":"mutation { generatePersonalApiKey { apiKey response { status message code } } }"}'

# Revoke, leaving the account with no key.
curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" -H "Content-Type: application/json" \
  -d '{"query":"mutation { deletePersonalApiKey { response { status message code } } }"}'
Operation Arguments Returns
verifyPersonalApiKey personalApiKey required, isCheckForBot required, botApiSecretKey API_KEY_VALID, or INVALID_API_KEY / API_ACCESS_DENIED / BOT_NOT_FOUND
generatePersonalApiKey none the new key in apiKey; PERSONAL_API_KEY_GENERATED
deletePersonalApiKey none PERSONAL_API_KEY_DELETED

Capture the new key from the response. generatePersonalApiKey returns it once, in apiKey, and invalidates the old key immediately — an automated rotation that fails to store the result locks itself out. Write the new key to your secret store before discarding the old one.

Set isCheckForBot: true with a botApiSecretKey to check the key against a particular bot as well as the account — that is the check the Chat API runs, and it is how you confirm a key can reach a bot before relying on it.

Not every account may mint keys: the business can restrict API access, and a key generation attempt from a restricted account returns 403 API_KEY_GENERATION_FORBIDDEN.

Scope by choosing the owner: create a dedicated service account at the lowest role that works, rather than issuing a key from a privileged human account.


Key hygiene

  • Store keys in environment variables or a secrets manager. Never commit them, and never ship one in browser or other client-side code.
  • Rotate on a schedule, and immediately if a key may have been exposed. Generating a new key from Admin → Profile invalidates the previous one.
  • Use a dedicated service account for integrations rather than a person's key. Scope that account to the minimum role that works, and it survives the person leaving.
  • Never send keys over email or chat.

Read this chapter before you write any error handling. StudioX does not signal failure the way most REST APIs do, and code that branches on the HTTP status code will treat failures as successes.


The response envelope

Every GraphQL operation returns its payload alongside a response object:

{
  "data": {
    "currentUser": {
      "user": { "id": "...", "email": "..." },
      "response": {
        "status": 200,
        "message": "Current user query has been successful",
        "code": "CURRENT_USER_QUERY_SUCCESSFUL"
      }
    }
  }
}
Field Type Meaning
response.status Integer HTTP-style status. This is the real result.
response.code String Stable machine-readable outcome. Branch on this.
response.message String Human-readable. Display it; never parse it.

Branch on response.code. Display response.message. Never parse message — it is prose, it is localised in places, and it changes without notice.


HTTP 200 does not mean success

A valid GraphQL request returns HTTP 200 even when the operation fails. Authentication failures, permission denials and quota exhaustion all arrive as HTTP 200 with the detail inside the body:

{
  "data": {
    "currentUser": {
      "user": null,
      "response": { "status": 401, "message": "Unauthorized", "code": "UNAUTHORIZED" }
    }
  }
}

That is a real response from production, sent with HTTP/2 200. Note that data is present and non-null while user is null — a client that checks only if (data) will sail straight past this and dereference null.

# WRONG — passes on every failure the platform produces
r = requests.post(url, headers=headers, json=payload)
r.raise_for_status()
user = r.json()["data"]["currentUser"]["user"]
print(user["email"])          # TypeError on any auth failure
# RIGHT
r = requests.post(url, headers=headers, json=payload)
r.raise_for_status()                       # catches transport/5xx only
body = r.json()

if "errors" in body:                       # request-level failure, see below
    raise RuntimeError(body["errors"][0]["message"])

result = body["data"]["currentUser"]
resp = result["response"]
if resp["status"] != 200:                  # operation-level failure
    raise RuntimeError(f'{resp["code"]}: {resp["message"]}')

print(result["user"]["email"])

The Chat API breaks this pattern in a third way — see Chat API.


Two different kinds of failure

1. Request-level — errors[], no envelope

Your query was rejected before any resolver ran: a malformed query, an unknown field, a missing required variable. The response has an errors array and usually no data at all.

{"errors":[{"message":"Cannot query field \"nope\" on type \"GetAIEngineVersionResponse\".",
            "locations":[{"line":1,"column":24}]}]}

Missing input fields are reported one error per field, which makes this the fastest way to discover what an input type actually requires:

{"errors":[
  {"message":"Variable \"$input\" got invalid value { rows: 10 }; Field \"keyword\" of required type \"String!\" was not provided."},
  {"message":"Variable \"$input\" got invalid value { rows: 10 }; Field \"linkedBusinessId\" of required type \"String!\" was not provided."},
  {"message":"Variable \"$input\" got invalid value { rows: 10 }; Field \"page\" of required type \"Int!\" was not provided."}
]}

These are bugs in your integration. They are not transient and retrying will not help. Always check errors first.

2. Operation-level — envelope with a non-200 response.status

The query was well-formed and ran. The platform declined it. data is present, the payload fields are null, and response carries the reason. These are the cases you handle at runtime: auth, permissions, quotas, not-found.


Status codes

Values you will see in response.status (and, for transport failures, as real HTTP codes):

Status Meaning Retry?
200 Success —
400 Bad request — invalid input, or a quota is exhausted No
401 Unauthorized — missing, invalid or revoked key No
403 Forbidden — authenticated, but not permitted No
404 Not found — bad endpoint, or the resource does not exist No
500 Internal error Yes, with backoff

Only 500 and genuine transport errors are worth retrying. Use exponential backoff with jitter. Retrying a 400 quota failure will never succeed — see Quotas.

For the full list of response.code values and what each one means, see Error codes.


Asynchronous operations

A 200 from an ingestion call means accepted, not finished.

addKnowledgebaseSource returns as soon as the source is queued. Behind it, StudioX creates an async operation and a scheduled task, then works through upload → pre-processing → text extraction → vector insert → post-processing. Depending on the file, that takes anywhere from seconds to many minutes.

addKnowledgebaseSource → 200 ADDED_TO_KNOWLEDGEBASE   ← queued, NOT searchable
        │
        ├─ upload → pre-process → extract → vectorise → post-process
        │
        └─ source becomes answerable by the bot

If you upload a document and immediately ask the bot about it, the bot will not know about it yet. This is the single most common "the API is broken" report, and it is the expected behaviour.

Poll for completion before you rely on the content. See Knowledge Base → Tracking ingestion.


Pagination

List queries share one convention:

Field Type Notes
page Integer 1-indexed. skip = page * rows - rows
rows Integer Page size. No maximum is enforced
keyword String Case-insensitive filter. Usually required — pass "" for no filter
sortField String Allowed values differ per query. Check the query's own table
sortDirection String "asc" or "desc"

Responses carry both counts, and they mean different things:

Field Meaning
count Rows matching the query including keyword
totalCount Rows matching ignoring keyword

Page through until you have collected count rows. Sizing your loop from totalCount while a keyword is set will make you page past the end.

keyword is required and accepts an empty string. Omitting it is a request-level error, not a default.


Identifiers

Almost every ID in StudioX is a 24-character hexadecimal MongoDB ObjectId, for example 68e94c6613b15f5ebb35d11a. Treat them as opaque strings — do not parse them, and do not assume ordering.

Where to obtain the ones you need:

ID Source
User ID getUsers → items[].id
Business ID currentUser → user.primaryBusiness
Bot ID Dashboard → AI Assistants → the bot's Config URL
Bot URL Dashboard → AI Assistants → the copy button on the bot card
Label ID getKnowledgebaseLabels → items[]._id
Source ID addKnowledgebaseSource → sourceId
Conversation ID Chat stream → conversationIdCreated event

Each operation's chapter repeats the ones it needs.


Versioning

The API is unversioned — there is no version in the path or in a header, and changes are additive wherever possible.

Build defensively:

  • Request only the fields you use. GraphQL returns exactly your selection set, so a new field added upstream cannot break your parser.
  • Never depend on field order, and never parse message strings.
  • Treat unknown response.code values as failures when status is not 200, rather than matching against a closed set.

Platform and user management. All operations are GraphQL, at <BASE_URL>/api/graphql/ with Authorization: <YOUR_API_KEY>.

Health check

Verify the platform is up. Unauthenticated — it does not validate your key.

curl -X POST $BASE_URL/api/graphql/ \
  -H "Content-Type: application/json" \
  -d '{"query":"{ getSystemHealthCheck { response { status message code } } }"}'
{"data":{"getSystemHealthCheck":{"response":{"status":200,"message":"Everything is fine","code":"1"}}}}

There is also a REST equivalent:

curl -X GET "$BASE_URL/api/healthCheck/"
{"message":"Everything is fine","code":0}

Note the REST form returns code as an integer 0, while the GraphQL form returns the string "1". Neither carries a status field. They are liveness probes, nothing more.

Neither endpoint validates credentials. Both return the same 200 with no key, a valid key or a garbage key. To check a key, use currentUser.


Get the current user

Returns the identity your API key resolves to. This is the correct way to test a key, and the source of the business ID most other calls need.

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ currentUser { user { id name email primaryBusiness role } response { status message code } } }"}'
{
  "data": {
    "currentUser": {
      "user": {
        "id": "b7c91f4a23d56789ef012345",
        "name": "Alex Johnson",
        "email": "alex.johnson@example.com",
        "primaryBusiness": "7d6e5c4b3a2109f8edc65432",
        "role": "business-admin"
      },
      "response": {
        "status": 200,
        "message": "Current user query has been successful",
        "code": "CURRENT_USER_QUERY_SUCCESSFUL"
      }
    }
  }
}
Field Type Description
user.id String User ID — use for user operations
user.name String Display name
user.email String Email address
user.primaryBusiness String Primary business ID — most admin calls need this
user.role String user, business-support, business-admin, business-super-admin

Failure modes: UNAUTHORIZED (401) for a bad or missing key, USER_NOT_FOUND (404) if the key's account no longer exists.


Get the AI engine version

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ getAIEngineVersion { aiEngineversion aiEngineDeployedDate response { status message code } } }"}'
{
  "data": {
    "getAIEngineVersion": {
      "aiEngineversion": "5e1ca6b",
      "aiEngineDeployedDate": "2025-09-09T19:34:58.0343449",
      "response": {
        "status": 200,
        "message": "Get AI Engine version query has been successful",
        "code": "GET_AI_ENGINE_VERSION_QUERY_SUCCESSFUL"
      }
    }
  }
}
Field Type Description
aiEngineversion String Deployed engine build identifier
aiEngineDeployedDate String (ISO 8601) When it was deployed

Note the lowercase v in aiEngineversion — it is not aiEngineVersion.

Unlike the health check this query is authenticated, which makes it a useful second signal: an invalid key returns 200 with null values and response.status: 401.


List users

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetUsers($input: UsersInput!) { getUsers(input: $input) { items { id name email role } count totalCount response { status message code } } }",
    "variables": {
      "input": {
        "rows": 25,
        "page": 1,
        "keyword": "",
        "sortDirection": "asc",
        "sortField": "email",
        "linkedBusinessId": "<BUSINESS_ID>",
        "areSpecificBusinessUsers": true
      }
    }
  }'
Parameter Type Required Description
rows Integer Yes Page size. No enforced maximum
page Integer Yes 1-indexed
keyword String Yes Matches name, phone or email, case-insensitive. Pass "" for no filter
sortDirection String Yes asc or desc
sortField String Yes name, email, phone, role
linkedBusinessId String Yes Business to query — from currentUser.user.primaryBusiness
areSpecificBusinessUsers Boolean No true limits results to linkedBusinessId
isIncludeAdmin Boolean No Include administrator accounts
selectedRoleToFilter String No One role: business-admin, business-super-admin, business-support, user

keyword is required and accepts an empty string; omitting it is a request-level error, not a default. sortField does not accept createdAt.

Response:

Field Type Description
items Array Matching users
count Integer Rows matching including keyword
totalCount Integer Rows matching ignoring keyword

Failure modes: PERMISSION_DENIED, USERS_ACCESS_DENIED, INVALID_LINKED_BUSINESS_ID, BUSINESS_NOT_FOUND.


Create a user

Requires a key owned by a business-admin or above. A user-role key gets NOT_AUTHORIZED.

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "operationName": "AddUserToBusiness",
    "query": "mutation AddUserToBusiness($input: AddBusinessUserInput!) { addUserToBusiness(input: $input) { code message status } }",
    "variables": {
      "input": {
        "name": "Jordan Lee",
        "role": "user",
        "email": "jordan.lee@example.com",
        "businesses": ["<BUSINESS_ID>"],
        "primaryBusiness": "<BUSINESS_ID>"
      }
    }
  }'

Input

Only name, role and email are required. Everything else is optional and falls back to the business default.

Parameter Type Required Description
name String Yes Full name
role String Yes user, business-support, business-admin, business-super-admin
email String Yes Must be unique
phone String No Phone number
businesses Array[String] No Business IDs the user may access
primaryBusiness String No Default business — should be in businesses
hasDeleteAccess Boolean No May delete resources
checkRoleDowngrade Boolean No Warn rather than silently downgrade an existing user
roleCannotBeChanged Boolean No Lock the role against SSO auto-provisioning
returnDuplicateError Boolean No Error on duplicate email instead of updating
useBusinessTokenLimit Boolean No Inherit the business per-request token limit
tokenLimit String No Custom per-request token limit
useBusinessMonthlyTokenLimit Boolean No Inherit the business monthly token limit
monthlyTokenLimit String No Custom monthly token limit
useBusinessStorageLimit Boolean No Inherit the business storage limit
storageLimit String No Custom storage limit, in GB
useBusinessDocsLimit Boolean No Inherit the business document-count limit
docsLimit String No Custom document-count limit
useBusinessPagesLimit Boolean No Inherit the business page-count limit
pagesLimit String No Custom page-count limit
overrideRoles Array[String] No AccessRoleMapping IDs. Non-empty stops SSO/SCIM syncing this user

Notes:

  • The role values are exactly those listed above. There is no isOwner field.
  • The limit fields are strings, not integers — "100000", not 100000.
  • No range is enforced on any limit field.
  • The limits configured here are the quotas described in Quotas.

Response

{"data":{"addUserToBusiness":{"code":"USER_ADDED","message":"User has been added","status":200}}}
response.code Status Meaning
USER_ADDED 200 Created
INVALID_EMAIL 400 Malformed email
DUPLICATE_USER_EMAIL 400 Email already in use
ROLE_DOWNGRADE_WARNING 400 Would downgrade an existing user; set checkRoleDowngrade deliberately
ROLE_ESCALATION_DENIED 403 Cannot grant a role above your own
UNAUTHORIZED_BUSINESS_ACCESS 403 Your key is not linked to that business
NOT_AUTHORIZED 401 Insufficient role
BUSINESS_NOT_FOUND 404 Unknown business ID
ERR_ADDING_USER 500 Server fault

The mutation does not return the created user's ID. Confirm with List users, filtering by the email you just created.


Update a user

Change a role, move someone between businesses, or adjust their limits. Only id is required — omit a field to leave it unchanged.

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "operationName": "UpdateUser",
    "query": "mutation UpdateUser($input: UpdateUserInput!) { updateUser(input: $input) { code message status } }",
    "variables": {
      "input": {
        "id": "<USER_ID>",
        "role": "business-admin",
        "useBusinessTokenLimit": false,
        "tokenLimit": "250000"
      }
    }
  }'
Parameter Type Required Description
id String Yes User to update — from getUsers → items[].id
name, email, phone, username String No Profile fields
role String No Same values as Create a user
businesses Array[String] No Replaces the list
primaryBusiness String No Default business
hasDeleteAccess, checkRoleDowngrade, roleCannotBeChanged Boolean No As on create
timezone String No IANA timezone
useBusiness*Limit / tokenLimit, monthlyTokenLimit, storageLimit, docsLimit, pagesLimit Boolean / String No The quotas
overrideRoles Array[String] No Non-empty stops SSO/SCIM syncing this user

The same rules as create apply: limits are strings, and you cannot grant a role above your own.

response.code Status Meaning
UPDATE_SUCCESS 200 Updated
INVALID_EMAIL 400 Malformed email
DUPLICATE_USER_EMAIL / DUPLICATE_USERNAME 400 Already in use
PERMISSION_DENIED / FORBIDDEN 403 Role too low for this change
CURRENT_USER_NOT_FOUND 404 The key's own account is missing

List businesses

getUsers needs a linkedBusinessId. If your key's account belongs to one business, take it from currentUser.user.primaryBusiness. If it belongs to several, enumerate them:

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetBusinesses($input: BusinessesInput!) { getBusinesses(input: $input) { items { id name } count totalCount response { status message code } } }",
    "variables": {
      "input": {
        "rows": 25,
        "page": 1,
        "keyword": "",
        "sortField": "name",
        "sortDirection": "asc",
        "linkedBusinessId": "<BUSINESS_ID>"
      }
    }
  }'

All of rows, page, keyword, sortField, sortDirection and linkedBusinessId are required — pass "" for keyword rather than omitting it. searchKey is optional.

Codes: BUSINESSES_QUERY_SUCCESSFUL (200), USER_NOT_LINKED_WITH_ANY_BUSINESS, BUSINESS_API_ACCESS_DENIED, USER_NOT_FOUND.


Delete a user

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "operationName": "DeleteUser",
    "query": "mutation DeleteUser($input: DeleteUserInput!) { deleteUser(input: $input) { code message status } }",
    "variables": {
      "input": {
        "id": "<USER_ID>",
        "doPermanentDelete": false,
        "deleteRequestUserBusiness": "<BUSINESS_ID>"
      }
    }
  }'
Parameter Type Required Description
id String Yes User to delete — from getUsers → items[].id
doPermanentDelete Boolean Yes false soft-deletes (recoverable); true is irreversible
deleteRequestUserBusiness String No Business context — from currentUser.user.primaryBusiness

doPermanentDelete: true cannot be undone over the API. Default to false unless you are certain.

response.code Status Meaning
USER_DELETED 200 Deleted
CANNOT_DELETE_YOURSELF 400 A key cannot delete its own account
USER_NOT_IN_BUSINESS 403 Target is not in the given business
INSUFFICIENT_BUSINESS_AUTHORITY 403 Your role is too low for this target
SYSTEM_USER_DELETION_FORBIDDEN 403 Platform-managed account
DELETE_USER_NOT_FOUND 404 Unknown user ID

Worked example: provision a user

API_KEY="<YOUR_API_KEY>"
GQL="$BASE_URL/api/graphql/"

# 1. Resolve your business ID
BUSINESS_ID=$(curl -s -X POST "$GQL" \
  -H "Authorization: $API_KEY" -H "Content-Type: application/json" \
  -d '{"query":"{ currentUser { user { primaryBusiness } } }"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["currentUser"]["user"]["primaryBusiness"])')

# 2. Create the user
curl -s -X POST "$GQL" \
  -H "Authorization: $API_KEY" -H "Content-Type: application/json" \
  -d "{
    \"query\": \"mutation AddUserToBusiness(\$input: AddBusinessUserInput!) { addUserToBusiness(input: \$input) { code message status } }\",
    \"variables\": { \"input\": {
      \"name\": \"Jordan Lee\",
      \"role\": \"user\",
      \"email\": \"jordan.lee@example.com\",
      \"businesses\": [\"$BUSINESS_ID\"],
      \"primaryBusiness\": \"$BUSINESS_ID\"
    }}
  }"

# 3. Confirm, and capture the new user's ID
curl -s -X POST "$GQL" \
  -H "Authorization: $API_KEY" -H "Content-Type: application/json" \
  -d "{
    \"query\": \"query GetUsers(\$input: UsersInput!) { getUsers(input: \$input) { items { id email role } count } }\",
    \"variables\": { \"input\": {
      \"rows\": 10, \"page\": 1,
      \"keyword\": \"jordan.lee@example.com\",
      \"sortDirection\": \"asc\", \"sortField\": \"email\",
      \"linkedBusinessId\": \"$BUSINESS_ID\",
      \"areSpecificBusinessUsers\": true
    }}
  }"

Check response.status in each body — none of these steps report failure through the HTTP status code. See Conventions and Errors.

A bot answers from its knowledge base. This chapter covers adding sources, tracking their ingestion, listing them, organising them with labels, and removing them.

All operations are GraphQL, at <BASE_URL>/api/graphql/ with Authorization: <YOUR_API_KEY>.

A bot can restrict which accounts may reach it over the API. If you get API_ACCESS_DENIED here, see Bots carry their own API access list.


Add a source

addKnowledgebaseSource accepts three kinds of source, and you supply exactly one of them:

You are adding Field to set Example dataSourceType
A file file pdf-document, docx-file, pptx-file, xlsx-file, video-file, audio-file
A link linkToDataSource url-addition, confluence, jira-ticket
Text plainTextSource plain-text

Supplying none of them fails with FILE_NOT_FOUND, LINK_TO_DATA_SOURCE_NOT_FOUND or PLAIN_TEXT_NOT_FOUND depending on what the dataSourceType expected.

Input

Parameter Type Required Description
botId String Yes Bot to add the source to
dataSourceType String Yes Source type key — see Data source types
title String Yes (see note) Display name
file File Conditional The upload, for file types
linkToDataSource String Conditional The URL / ticket ID, for link types
plainTextSource String Conditional The text, for plain-text
description String No Longer description
stringifiedUniqueParameters String (JSON) No Access control and options — below

On title: the GraphQL schema marks it optional, but the resolver rejects a request without one (400 TITLE_NOT_FOUND). Treat it as required. The only exception is spreadsheet URL extraction (shouldExtractUrlsFromSpreadsheet: true).

Response

{
  "data": {
    "addKnowledgebaseSource": {
      "status": 200,
      "message": "Added to knowledgebase. SourceID: 68f4246241780c17c674a742",
      "code": "ADDED_TO_KNOWLEDGEBASE",
      "sourceId": "68f4246241780c17c674a742"
    }
  }
}
Field Type Description
status Integer 200 on acceptance
code String ADDED_TO_KNOWLEDGEBASE on success
message String Human-readable. Also repeats the source ID — do not parse it
sourceId String The created source's ID. Select this field and use it.

Select sourceId. It is a real field on the response. Earlier documentation told readers to extract the ID from the message string — do not do that. message is prose and is free to change.

A 200 here means queued, not searchable. Ingestion is asynchronous. See Tracking ingestion.

Adding a file

File uploads use the GraphQL multipart request spec: an operations part holding the query, a map part binding a file to a variable, and the file itself.

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -F 'operations={
    "operationName": "AddKnowledgebaseSource",
    "query": "mutation AddKnowledgebaseSource($input: AddKnowledgebaseSourceInput!) { addKnowledgebaseSource(input: $input) { status message code sourceId } }",
    "variables": {
      "input": {
        "title": "Q3 Technical Whitepaper",
        "description": "PDF parsing and table extraction.",
        "botId": "<BOT_ID>",
        "dataSourceType": "pdf-document",
        "file": null,
        "stringifiedUniqueParameters": "{\"approvedUsers\":[],\"approvedGroupIds\":[],\"labels\":[],\"autoRestrict\":false,\"authRequired\":false,\"businessRestricted\":false,\"isTemporary\":false}"
      }
    }
  }' \
  -F 'map={"0":["variables.input.file"]}' \
  -F '0=@/path/to/whitepaper.pdf'

Do not set Content-Type yourself — curl sets the multipart boundary. The file variable is null inside operations; map is what binds part 0 to it.

Adding a URL

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "operationName": "AddKnowledgebaseSource",
    "query": "mutation AddKnowledgebaseSource($input: AddKnowledgebaseSourceInput!) { addKnowledgebaseSource(input: $input) { status message code sourceId } }",
    "variables": {
      "input": {
        "title": "Supplier onboarding policy",
        "botId": "<BOT_ID>",
        "dataSourceType": "url-addition",
        "linkToDataSource": "https://example.com/policies/supplier-onboarding",
        "stringifiedUniqueParameters": "{\"labels\":[],\"businessRestricted\":false}"
      }
    }
  }'

The page is fetched and indexed server-side. It must be reachable from StudioX — pages behind your VPN or a login will fail during processing, not at this call.

Adding plain text

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "operationName": "AddKnowledgebaseSource",
    "query": "mutation AddKnowledgebaseSource($input: AddKnowledgebaseSourceInput!) { addKnowledgebaseSource(input: $input) { status message code sourceId } }",
    "variables": {
      "input": {
        "title": "Support escalation policy",
        "botId": "<BOT_ID>",
        "dataSourceType": "plain-text",
        "plainTextSource": "Tier 1 escalates to Tier 2 after 30 minutes...",
        "stringifiedUniqueParameters": "{\"labels\":[],\"businessRestricted\":true}"
      }
    }
  }'

Useful for policies, FAQs and snippets that have no source document.

Adding Confluence and JIRA

Same shape as a URL, with linkToDataSource carrying the page URL or ticket key, and dataSourceType set to confluence or jira-ticket. These require linked-source credentials configured on the bot — set those up in the dashboard first, or ingestion fails during processing.

confluenceLabels in stringifiedUniqueParameters narrows a Confluence space to pages carrying specific labels.

Access control and options

stringifiedUniqueParameters is a JSON string, not an object — serialise it and pass the result.

Field Type Description
approvedUsers Array[String] User IDs that may see this source. [] = no per-user restriction
approvedGroupIds Array[String] Group IDs that may see it. [] = no group restriction
labels Array[String] Label IDs to tag the source with — Labels
hasSemanticLabels Boolean Labels are matched semantically rather than exactly
autoRestrict Boolean Derive restrictions from document content
authRequired Boolean Only signed-in users may retrieve from this source
businessRestricted Boolean Restrict to users in the same business
isTemporary Boolean Scope the source to a single conversation
conversationId String Required when isTemporary is true
uploadedBy String Attribute the upload to a specific user
confluenceLabels Array[String] Confluence label filter
shouldExtractUrlsFromSpreadsheet Boolean Treat a spreadsheet as a list of URLs to ingest

Temporary sources are for "chat with this document" flows: set isTemporary and the conversationId from the chat stream's conversationIdCreated event, and the source is scoped to that conversation rather than the permanent knowledge base.


Tracking ingestion

After addKnowledgebaseSource returns, StudioX works through upload → pre-processing → extraction → vectorisation → post-processing. Until that finishes, the bot cannot answer from the source.

Poll getKnowledgebaseSources and watch the source you just created:

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetKnowledgebaseSources($input: GetKnowledgebaseSourcesInput!) { getKnowledgebaseSources(input: $input) { items { _id title hasCompleted progressPercent progressMessage hasExhaustedRetries approvalStatus pendingReason } count hasMore response { status message code } } }",
    "variables": {
      "input": {
        "botId": "<BOT_ID>",
        "rows": 25,
        "page": 1,
        "keyword": "",
        "sortField": "createdAt",
        "sortDirection": "desc",
        "dataTypeFilter": ""
      }
    }
  }'
Field Meaning
hasCompleted true once processing finished. This is your completion signal.
progressPercent 0–100
progressMessage Human-readable current stage
hasExhaustedRetries true means processing failed permanently (3 retries used)
approvalStatus pending, approved or rejected
pendingReason admin_review, or limit_exceeded if the uploader hit a docs/pages cap

Poll on a modest interval — a few seconds — and back off for large files. A large PDF can take many minutes.

Two states that are not failures but still mean the bot cannot answer yet:

  • approvalStatus: "pending" — the source is waiting on a human. If pendingReason is limit_exceeded, an administrator must raise the cap; see Quotas.
  • hasCompleted: true with hasExhaustedRetries: true — processing finished by giving up. Check the source's errors in the dashboard.

getAsyncTasksByOperationId exposes the individual processing tasks, but it requires business-admin tier or above and the parent operation ID, which addKnowledgebaseSource does not return. getKnowledgebaseSources is the supported way to track a source you created.


List sources

getKnowledgebaseSources is also the general listing query.

Parameter Type Required Description
botId String Yes Bot to list
rows Integer Yes Page size
page Integer Yes 1-indexed page
keyword String Yes Search filter — pass "" for none
sortField String Yes title, name, createdAt, updatedAt
sortDirection String Yes asc or desc
dataTypeFilter String Yes Source type filter — pass "" for all
labels Array[String] No Match any of these label IDs
label String No Single label. labels wins when both are set
group String No Filter by group
category String No Filter by category
restriction String No Filter by restriction
linkedSourceType String No Filter by linked source type
conversationId String No Only sources scoped to this conversation
showErroredDocumentsOnly Boolean No Only sources that exhausted retries

Note that keyword, sortField, sortDirection and dataTypeFilter are all required — empty strings, not omission.

Counts on this query

This query's counts behave differently from the rest of the platform, because large knowledge bases are counted from a snapshot:

Field Meaning
hasMore Use this to drive pagination. True when another page exists
countExact Whether count is authoritative
count Exact for single-filter and snapshot-served queries; an upper bound capped at 10,000 otherwise
totalCount Identical to count, kept for older callers
snapshotCount Instant exact count when the filter is snapshot-servable, else null

Page with hasMore, not with count. On a large knowledge base with multiple filters, count can be an upper bound, and looping until you have collected count rows will run past the end.


Labels

Labels group sources so chat can be scoped to a subset — they are what selectedLabels on the Chat API filters by, and what the labels key in stringifiedUniqueParameters tags a source with.

Create a label

A new bot has no labels. Create one before you can tag anything with it.

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "operationName": "AddKnowledgebaseLabel",
    "query": "mutation AddKnowledgebaseLabel($input: AddKnowledgebaseLabelInput!) { addKnowledgebaseLabel(input: $input) { status message code } }",
    "variables": {
      "input": {
        "botId": "<BOT_ID>",
        "label": "hr-policies",
        "description": "Human resources policy documents",
        "isSemanticLabel": false
      }
    }
  }'
Parameter Type Required Description
botId String Yes Bot the label belongs to
label String Yes Label name
description String No What the label is for
isSemanticLabel Boolean No Match semantically rather than exactly

The new label's ID comes back in message. This one mutation has no structured ID field — on success, message is the ID and nothing else:

{"data":{"addKnowledgebaseLabel":{"status":200,
 "message":"68aa019574cd7aa7055c5e20","code":"LABEL_CREATED"}}}

Read it only when code is LABEL_CREATED; on failure message carries an error string instead. This is the one place in the API where parsing message is correct, and it is the exception that proves the rule.

Codes: LABEL_CREATED (200), NOT_AUTHORIZED / API_ACCESS_DENIED (401), ERROR_CREATING_LABEL (500).

List labels

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetKnowledgebaseLabels($input: GetKnowledgebaseLabelsInput!) { getKnowledgebaseLabels(input: $input) { items { _id label description isSemanticLabel } count totalCount response { status message code } } }",
    "variables": {
      "input": {
        "botId": "<BOT_ID>",
        "page": 1,
        "rows": 100,
        "keyword": "",
        "sortField": "updatedAt",
        "sortDirection": "desc"
      }
    }
  }'
Parameter Type Required Description
botId String Yes Bot whose labels to list
page Integer Yes 1-indexed
rows Integer Yes Page size
keyword String Yes Filter by name. Pass "" for no filter
sortField String Yes updatedAt, createdAt, label
sortDirection String Yes asc or desc

Response items:

Field Type Description
_id String Label ID — this is what selectedLabels takes
label String Display name
description String Description
isSemanticLabel Boolean Matched semantically rather than exactly

Pass _id values, not label names, to selectedLabels and to the labels key in stringifiedUniqueParameters.

Rename or delete a label

# Rename, or change the description. Only labelId is required; omit a field to leave it.
curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" -H "Content-Type: application/json" \
  -d '{
    "query": "mutation UpdateKnowledgebaseLabel($input: UpdateKnowledgebaseLabelInput!) { updateKnowledgebaseLabel(input: $input) { status message code } }",
    "variables": { "input": { "labelId": "<LABEL_ID>", "label": "hr-policies-2026" } }
  }'

# Delete. Sources keep their other labels; only this tag is removed.
curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" -H "Content-Type: application/json" \
  -d '{
    "query": "mutation DeleteKnowledgebaseLabel($input: DeleteKnowledgebaseLabelInput!) { deleteKnowledgebaseLabel(input: $input) { status message code } }",
    "variables": { "input": { "labelId": "<LABEL_ID>" } }
  }'
Operation Required Optional
updateKnowledgebaseLabel labelId label, description
deleteKnowledgebaseLabel labelId —

Codes: LABEL_UPDATED / LABEL_DELETED (200), LABEL_NOT_FOUND (404), NOT_AUTHORIZED (401), ERROR_UPDATING_LABEL / ERROR_DELETING_LABEL (500).


Delete a source

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "operationName": "DeleteKnowledgebaseSource",
    "query": "mutation DeleteKnowledgebaseSource($input: DeleteKnowledgebaseSourceInput!) { deleteKnowledgebaseSource(input: $input) { code message status } }",
    "variables": {
      "input": {
        "botId": "<BOT_ID>",
        "sourceId": "<SOURCE_ID>"
      }
    }
  }'
Parameter Type Required Description
botId String Yes Bot the source belongs to
sourceId String Yes From addKnowledgebaseSource → sourceId, or getKnowledgebaseSources → items[]._id
{
  "data": {
    "deleteKnowledgebaseSource": {
      "code": "DOCUMENT_DELETED",
      "message": "Document has been deleted",
      "status": 200
    }
  }
}

Deletion removes the source and its vectors. It is not reversible over the API — re-add the source to restore it.


Errors

response.code Status Meaning
ADDED_TO_KNOWLEDGEBASE 200 Accepted and queued
DOCUMENT_DELETED 200 Deleted
TITLE_NOT_FOUND 400 No title supplied
FILE_NOT_FOUND 400 Type expected a file
LINK_TO_DATA_SOURCE_NOT_FOUND 400 Type expected a linkToDataSource
PLAIN_TEXT_NOT_FOUND 400 Type expected a plainTextSource
UPLOAD_FUNCTION_NOT_FOUND 400 Unrecognised dataSourceType
PIPELINE_NOT_FOUND 400 No processing pipeline for this type on this bot
SOURCE_DECLINED_SKIPPED 200 Rejected by the bot's approval rules
API_ACCESS_DENIED 401 Key valid, but not on this bot's API access list
NOT_AUTHORIZED 401 Not permitted to add sources to this bot
ERR_TO_ADD_KNOWLEDGEBASE 500 Server fault — retry with backoff
TOKEN_LIMIT_EXCEEDED etc. 400 A quota is exhausted — Quotas

Full list in Error codes.

Send a message to a StudioX bot and receive a streamed conversational response grounded in that bot's knowledge base.

POST <BASE_URL>/api/chatbot/chat/
Header Value
Content-Type application/json
personal-api-key <YOUR_API_KEY>

This endpoint uses personal-api-key, not Authorization. It is the only StudioX surface that does. Authorization is ignored here — see Authentication.

Two modes: choose before you build

The same endpoint serves two completely different response protocols, selected by a query parameter:

Default ?streaming=true
Protocol Vercel AI SDK v3 data stream Real Server-Sent Events
Framing 0:"token" / 2:[{...}] lines event: <name> + data: <json> + blank line
Standard SSE clients ✗ cannot parse ✓ work directly
Auth failures HTTP 200, error streamed as an answer Real 401 / 403 with a JSON body
Structured events 9 processType values Named events with eventName payloads
Served by The front-end orchestration pipeline Proxied to the platform's own SSE engine

Prefer ?streaming=true for new integrations. It is the better-behaved protocol: standard SSE tooling reads it, failures arrive as real status codes, and workflow events are structured. See Streaming mode.

The default mode is documented here because existing integrations use it, and because its auth behaviour is a trap worth understanding.


Authentication failures do not return 401

⚠️ Read this before writing a client.

In default mode, when authentication fails this endpoint returns HTTP 200 and streams the error message back as if it were the bot's answer. There is no 401, no errors array, and no machine-readable failure flag in the stream.

?streaming=true does not behave this way — it returns real 401 and 403 responses. This entire section applies to default mode only.

A request with an invalid key produces a perfectly ordinary-looking stream:

0:"The"  0:" API"  0:" key"  0:" you"  0:" provided"  0:" is"  0:" invalid"
0:"."  0:" Please"  0:" check"  0:" your"  0:" key"  0:" and"  0:" try"  0:" again"  0:"."

Concatenated, that is a sentence. A client that calls raise_for_status() and prints the assembled text will display an authentication error to the user as a bot response, log it as a successful conversation, and never alert anyone.

Detect it by matching the assembled response against the known failure strings before treating it as an answer:

Condition Message
Invalid key The API key you provided is invalid. Please check your key and try again.
Key valid, no access to this bot You do not have permission to access this bot. Please contact the administrator to request access.
Bot missing or reconfigured This bot could not be found. It may have been removed or its configuration has changed.
Bot misconfigured Bot configuration error: Missing API secret key. Please contact the administrator.
Verification failed upstream An error occurred while verifying your API key. Please try again later.
Neither session nor key Access restricted. Please sign in or provide a valid API key to continue using this bot.
Anything else Authentication failed: <reason>

A reliable signal that these are errors rather than answers: an authentication failure emits no conversationIdCreated event. If the stream ends and you never saw one on a new conversation, you did not talk to the bot.

There is a worked guard in Parsing the stream below.


Access modes

Mode Header When
Authenticated personal-api-key: <YOUR_API_KEY> Default
Anonymous (none) Only if the bot has Require Sign-in for Bot Access set to False

To allow anonymous access: Dashboard → AI Assistants → Config → Settings → Bot Features → Configure → Require Sign-in for Bot Access → False.

!Bot Configuration, Settings tab, showing the Bot Features card

!Require Sign-in for Bot Access set to False

Note the interaction with the header mistake above: against an anonymous-enabled bot, a request sending the key as Authorization succeeds — anonymously. It will keep succeeding until sign-in is re-enabled, at which point every such integration starts returning auth errors as chat messages.


Request

{
  "messages": [
    { "role": "assistant", "content": "Hello! How can I help you today?" },
    { "role": "user", "content": "What information is available in the documents?" }
  ],
  "data": {
    "conversationId": "",
    "botUrl": "<BASE_URL>/bot",
    "lang": "en",
    "selectedLabels": [],
    "selectedCategories": [],
    "responseStyle": "normalResponse"
  }
}

messages

Field Type Required Description
messages Array Yes Conversation history, oldest first
messages[].role String Yes "user" or "assistant"
messages[].content String Yes Message text

The last entry should be the user turn you want answered.

data

Field Type Required Description
botUrl String Yes The bot's full URL — see below
conversationId String No "" or omitted starts a new conversation; a prior ID continues one
lang String No Language code. Default "en"
responseStyle String No conciseResponse · normalResponse (default) · detailedResponse
selectedLabels Array[String] No Restrict retrieval to these label IDs. [] = all
selectedCategories Array[String] No Restrict retrieval to these source types. [] = all
selectedFilterObjects Array No Structured retrieval filters, as built by the bot's search filter UI
oneShotMessage Boolean No Answer without persisting the turn to conversation history
guessedTimezone String No IANA timezone (e.g. America/Los_Angeles) for date-relative questions
alwaysTriggerRefetch Boolean No Force a refetchTrigger event even when nothing changed
userUpdatedTitle String No Override the auto-generated conversation title
conversationClosed Boolean No Mark the conversation closed after this turn
botApiSecret String No Per-request override of the bot's API secret
uniqueData Object No Workflow feature flags and knowledge-source selectors, passed through to the bot's vibe workflows. Contents are bot-specific
listenerType String No Trigger type passed to the workflow. Defaults to "ChatBot"

selectedCategories

Value Content
pdf-document PDF files
docx-file Word documents
pptx-file PowerPoint presentations
xlsx-file Excel spreadsheets
plain-text Plain text
url-addition Web URLs
video-file Video
audio-file Audio
confluence Confluence pages
datasheet-pdf Datasheet PDFs

These are the same identifiers used by dataSourceType on Knowledge Base. Do not guess at variants — there is no docx-document or pptx-document. The authoritative list for your tenant comes from the data source types query.

Finding your botUrl

Dashboard → AI Assistants. Each bot card shows its URL with a copy button.

!AI Assistants list showing the bot URL

The host is your installation; the path identifies the bot. The examples use $BASE_URL/bot, the default assistant — your own bots have their own paths, so copy the whole URL from that card rather than adapting the examples.


Response

The response is a stream, returned with HTTP 200 and Content-Type: text/event-stream.

The payload is not Server-Sent Events. Despite the content type, the body uses the Vercel AI SDK v3 data stream protocol. There are no data: prefixes, no event: lines and no blank-line record separators, so EventSource, sseclient-py and other standard SSE clients will not parse it. Read it as newline-delimited prefix:payload frames, or use the Vercel AI SDK client.

Each line is <prefix>:<json>:

Prefix Type Payload
0: Content token A JSON string — one fragment of the answer
2: Process event A JSON array of event objects
2:[{"processType":"conversationIdCreated","processData":"68e94c6613b15f5ebb35d11a","processId":1}]
2:[{"processType":"processingMessage","processData":true,"processId":1}]
0:"I'm"
0:" here"
0:" to"
0:" help"
0:"!"
2:[{"processType":"refetchTrigger","processData":true,"processId":2}]
2:[{"processType":"processingMessage","processData":false,"processId":3}]

Concatenating the 0: payloads gives I'm here to help!.

Each 0: payload is a JSON-encoded string — decode it before concatenating, or escapes and quotes will leak into your output.

Process events

processType processData Meaning
conversationIdCreated String New conversation started. Capture this to continue the thread.
processingMessage Boolean true at start, false at completion
refetchTrigger Boolean Client should refresh conversation lists
keepAlive (absent) Idle heartbeat, ~every 15s. Ignore it — see below
llmFallbackNotice Object The primary model was unavailable; a fallback answered
explainabilityEvent Object Retrieval/citation detail for the current answer
followupQuestionAddition Array Suggested follow-up questions
handleGoodbye Boolean The bot considers the conversation concluded
authorizationRequired Array A Vibes workflow needs credentials before it can continue

keepAlive frames exist to hold the connection open under proxies that drop idle streams after 30–60 seconds. They carry processId: 0 and no processData. Treat any unrecognised processType the same way: ignore it and keep reading. New event types are added without notice.


Parsing the stream

import json
import requests

BASE_URL = "https://www.studiox-ai.com"   # your StudioX installation
API_KEY = "<YOUR_API_KEY>"

CHAT_API_URL = f"{BASE_URL}/api/chatbot/chat/"
BOT_URL = f"{BASE_URL}/bot"

AUTH_FAILURES = (
    "The API key you provided is invalid.",
    "You do not have permission to access this bot.",
    "This bot could not be found.",
    "Bot configuration error: Missing API secret key.",
    "An error occurred while verifying your API key.",
    "Access restricted. Please sign in or provide a valid API key",
    "Authentication failed:",
)


def ask(question, conversation_id=""):
    payload = {
        "messages": [
            {"role": "assistant", "content": "Hello! How can I help you today?"},
            {"role": "user", "content": question},
        ],
        "data": {
            "conversationId": conversation_id,
            "botUrl": BOT_URL,
            "responseStyle": "normalResponse",
        },
    }

    parts, new_conversation_id = [], conversation_id

    with requests.post(
        CHAT_API_URL,
        headers={"Content-Type": "application/json", "personal-api-key": API_KEY},
        json=payload,
        stream=True,
        timeout=(10, 300),
    ) as response:
        response.raise_for_status()

        for line in response.iter_lines(decode_unicode=True):
            if not line:
                continue

            prefix, _, raw = line.partition(":")

            if prefix == "0":
                parts.append(json.loads(raw))       # decode — do not strip quotes

            elif prefix == "2":
                for event in json.loads(raw):
                    if event.get("processType") == "conversationIdCreated":
                        new_conversation_id = event["processData"]
                    # every other processType, known or not, is safely ignored

    answer = "".join(parts)

    # The endpoint returns 200 and streams auth errors as content. Guard for it.
    if not conversation_id and not new_conversation_id:
        if answer.startswith(AUTH_FAILURES):
            raise RuntimeError(f"StudioX chat authentication failed: {answer}")

    return answer, new_conversation_id


answer, conversation_id = ask("What information is available in the documents?")
print(answer)

# Continue the same thread
follow_up, conversation_id = ask("Summarise that in one sentence.", conversation_id)
print(follow_up)

Set a generous read timeout. Grounded answers over a large knowledge base can take well over a minute before the first token, and keepAlive frames are what keep the socket open in between.


Conversation flow

Goal How
Start a conversation "conversationId": "", or omit it
Continue a conversation Pass the conversationId from conversationIdCreated
Restrict to labelled documents "selectedLabels": ["<label_id>", ...]
Restrict to source types "selectedCategories": ["pdf-document", ...]
Search everything Leave both arrays []

The bot retains context for the life of a conversationId, so you do not need to resend prior turns in messages once you are passing one — though doing so is harmless.

Label IDs come from getKnowledgebaseLabels — see Knowledge Base → Labels.


Examples

Anonymous

Only works if the bot has sign-in disabled.

curl -N -X POST "$BASE_URL/api/chatbot/chat/" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "assistant", "content": "Hello! How can I help you today?" },
      { "role": "user", "content": "What can you help me with?" }
    ],
    "data": { "botUrl": "$BASE_URL/bot" }
  }'

Authenticated

curl -N -X POST "$BASE_URL/api/chatbot/chat/" \
  -H "Content-Type: application/json" \
  -H "personal-api-key: <YOUR_API_KEY>" \
  -d '{
    "messages": [
      { "role": "assistant", "content": "Hello! How can I help you today?" },
      { "role": "user", "content": "What information is available in the documents?" }
    ],
    "data": { "botUrl": "$BASE_URL/bot" }
  }'

Filtered by label, continuing a conversation

curl -N -X POST "$BASE_URL/api/chatbot/chat/" \
  -H "Content-Type: application/json" \
  -H "personal-api-key: <YOUR_API_KEY>" \
  -d '{
    "messages": [
      { "role": "assistant", "content": "Hello! How can I help you today?" },
      { "role": "user", "content": "What changed in the Q3 policy documents?" }
    ],
    "data": {
      "conversationId": "68e94c9a2c38e917b874b15c",
      "botUrl": "$BASE_URL/bot",
      "selectedLabels": ["68aa019574cd7aa7055c5e20"],
      "responseStyle": "detailedResponse"
    }
  }'

curl -N disables buffering so you see tokens as they arrive.


Streaming mode (real SSE)

POST <BASE_URL>/api/chatbot/chat?streaming=true

Same endpoint, same personal-api-key header, same { messages, data } body. The query parameter switches the response to standard Server-Sent Events, served by the platform's own streaming engine rather than the front-end pipeline.

Use this for new integrations.

What changes

  • Real HTTP status codes. 400 for a missing user message, 401 for missing authentication, 403 with {"code": "SIGNIN_REQUIRED"} when the bot requires sign-in, 404 when the bot cannot be resolved. Auth failures are not streamed as content.
  • Standard SSE framing, so EventSource, sseclient-py, httpx-sse and every other SSE client work without custom parsing.
  • Heartbeats are SSE comments (: heartbeat, every 15 s), which conforming clients discard automatically. Nothing to filter by hand.
  • Structured workflow events carrying typed payloads.

Request translation

Your { messages, data } body is translated for you: the last user message becomes the query, and conversationId, lang, guessedTimezone, responseStyle, botUrl, uniqueData and listenerType are passed through. Earlier messages are not resent — conversation context comes from conversationId.

Events

Event Payload Meaning
stream:connected {streamId, conversationId, botId, timestamp} Stream open. Capture conversationId here
stream:stage {stage, status} Pipeline progress: init, language_detection, vibes, answer, each started/completed
stream:text:start {source} Answer beginning. source is chat or vibe
stream:text {token, index} One fragment of the answer
stream:text:end {fullText} Answer complete, with the whole text
stream:event {eventName, data} A structured workflow event — see below
stream:authorization_required Array A workflow needs credentials before continuing
stream:error {error, stage, stepId, code} Failure during the stream
stream:done {conversationId, status, message, uniqueData} Final event; the stream then closes

stream:text:end carries the complete answer, so you can use it directly instead of accumulating tokens — useful when you do not need progressive display.

stream:event is bot-specific. Its eventName and data are defined by the vibe workflows a given bot runs — classification, escalation, lookups and so on. Match on eventName, ignore names you do not recognise, and consult the bot's own integration notes for the set it emits.

Example

curl -N -X POST "$BASE_URL/api/chatbot/chat?streaming=true" \
  -H "Content-Type: application/json" \
  -H "personal-api-key: <YOUR_API_KEY>" \
  -d '{
    "messages": [
      { "role": "user", "content": "What information is available in the documents?" }
    ],
    "data": {
      "botUrl": "$BASE_URL/bot",
      "responseStyle": "normalResponse"
    }
  }'
event: stream:stage
data: {"stage":"init","status":"started"}

event: stream:connected
data: {"streamId":"9fe53a2b-...","conversationId":"6aac4b26f578de38185813ce","botId":"6785722b...","timestamp":"2026-09-17T20:18:46.044Z"}

event: stream:stage
data: {"stage":"init","status":"completed","conversationId":"6aac4b26f578de38185813ce"}

Client

import json
import httpx

BASE_URL = "https://www.studiox-ai.com"   # your StudioX installation
URL = f"{BASE_URL}/api/chatbot/chat?streaming=true"


def ask(question, conversation_id=None, api_key="<YOUR_API_KEY>"):
    payload = {
        "messages": [{"role": "user", "content": question}],
        "data": {
            "botUrl": f"{BASE_URL}/bot",
            "conversationId": conversation_id,
            "responseStyle": "normalResponse",
        },
    }

    answer, new_id = "", conversation_id
    event = None

    with httpx.stream(
        "POST", URL, json=payload,
        headers={"personal-api-key": api_key},
        timeout=httpx.Timeout(10.0, read=300.0),
    ) as r:
        # Real status codes here — unlike default mode, this is meaningful.
        if r.status_code != 200:
            r.read()
            raise RuntimeError(f"{r.status_code}: {r.text}")

        for line in r.iter_lines():
            if not line:                      # blank line ends a record
                event = None
                continue
            if line.startswith(":"):          # heartbeat comment
                continue
            if line.startswith("event:"):
                event = line[6:].strip()
            elif line.startswith("data:"):
                data = json.loads(line[5:].strip())
                if event == "stream:connected":
                    new_id = data["conversationId"]
                elif event == "stream:text:end":
                    answer = data["fullText"]
                elif event == "stream:error":
                    raise RuntimeError(f'{data.get("code")}: {data.get("error")}')

    return answer, new_id


answer, conversation_id = ask("What information is available in the documents?")
print(answer)

No guard against auth-errors-as-answers is needed here — a bad key raises on the status code.


Error handling

Situation Default mode ?streaming=true
Invalid / missing key HTTP 200, error streamed as content 401 JSON
Bot requires sign-in HTTP 200, streamed as content 403 SIGNIN_REQUIRED
No user message in messages Answered as an empty turn 400 JSON
Unknown or unreachable botUrl HTTP 200, streamed as content 404 JSON
Malformed JSON body 400 400
Quota exhausted Streamed as content — see Quotas stream:error event
Server fault 500 500, or stream:error once the stream is open
Connection drops mid-stream Partial answer. Retry the turn; conversation state is already persisted Same

In default mode most failures arrive as HTTP 200 with prose in the stream, so transport-level codes catch only a narrow band of them. In streaming mode they arrive as real status codes before the stream opens, or as a stream:error event after. This is the main practical reason to prefer streaming mode.

<BASE_URL>/apidocs

The StudioX API Workbench is an in-browser GraphQL explorer, powered by Yoga GraphiQL. It combines a schema browser, a query editor and a live results panel, so you can discover operations and run them against your own data without writing any code.

Open it in a browser while signed in to StudioX.

Anything you run in the Workbench runs against real data with your permissions. Prefer queries over mutations while exploring.


Layout

Panel Purpose
Docs The schema explorer — every query, mutation, input and type
History Queries you have already run
Collections Saved queries
Settings Theme and editor preferences

Editor shortcuts: Ctrl+Space autocomplete · Ctrl+Enter run · Shift+Ctrl+P prettify · Shift+Ctrl+M merge fragments.


Reading the schema

Expand Query or Mutation in the Docs panel to list operations. For each one the explorer shows its arguments and return type, and every type links to its own fields.

Two conventions to read by:

  • ! means required. input: AddKnowledgebaseSourceInput! requires the argument; inside an input type, botId: String! requires that field.
  • Almost every operation returns a response object alongside its payload. Always select it — response { status message code } is where success or failure is reported. See Conventions and Errors.

The Docs panel is the authoritative source for required-ness and field names.

Some internal operations are marked deprecated and hidden from the explorer. They are not part of the supported surface; do not build on them.


A first query

{
  currentUser {
    user { id name email primaryBusiness role }
    response { status message code }
  }
}

Run it and the results panel mirrors your selection set exactly — GraphQL returns the fields you asked for and nothing else. That is what makes it safe to select narrowly and stay compatible as the schema grows.

A query with variables

Most real operations take an input object. Put the query in the editor:

query GetUsers($input: UsersInput!) {
  getUsers(input: $input) {
    items { id name email role }
    count
    totalCount
    response { status message code }
  }
}

and the variables in the Query Variables pane at the bottom:

{
  "input": {
    "rows": 25,
    "page": 1,
    "keyword": "",
    "sortDirection": "asc",
    "sortField": "email",
    "linkedBusinessId": "<BUSINESS_ID>",
    "areSpecificBusinessUsers": true
  }
}

Omit a required field and the response names it precisely:

Variable "$input" got invalid value { rows: 25 };
Field "keyword" of required type "String!" was not provided.

That is the fastest way to discover what an input really requires — one error per missing field.


Authentication in the Workbench

The Workbench uses your signed-in session, not your API key. Two consequences follow:

  • A query that works here can still fail from your code if your API key's account has a lower role than the one you are signed in as.
  • A bot that restricts API access can refuse your key while the Workbench succeeds, so addKnowledgebaseSource can work here and return API_ACCESS_DENIED from your integration. See Authentication.

Confirm anything you intend to automate by running it once with your real API key over curl.


Workflow

Docs → find the operation and its inputs · Editor → compose and run · Results → inspect the response, including response.status.

Once a query does what you want, save it to Collections, then translate it into a request — the query string and the variables object map directly onto the JSON body shown throughout this guide.

The dataSourceType identifier on addKnowledgebaseSource and the values in selectedCategories on the Chat API come from the same set.


Query the live list

This query is authoritative. Prefer it to the table below — types are added over time, and availability varies by tenant.

curl -X POST $BASE_URL/api/graphql/ \
  -H "Authorization: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query GetKnowledgebaseDataSourceTypes($input: GetKnowledgebaseDataSourceTypesInput!) { getKnowledgebaseDataSourceTypes(input: $input) { items { _id title dataSourceTypeKey } count totalCount response { status message code } } }",
    "variables": {
      "input": {
        "rows": 100,
        "page": 1,
        "keyword": "",
        "sortField": "title",
        "sortDirection": "asc"
      }
    }
  }'

dataSourceTypeKey is the value to pass as dataSourceType.

All five input fields are required — pass "" for keyword rather than omitting it.


Common types

Key Content Supply
pdf-document PDF file
docx-file Word document file
pptx-file PowerPoint presentation file
xlsx-file Excel spreadsheet file
video-file Video (transcribed) file
audio-file Audio (transcribed) file
datasheet-pdf Datasheet PDF, specialised extraction file
plain-text Text plainTextSource
url-addition Web page linkToDataSource
confluence Confluence page or space linkToDataSource
jira-ticket JIRA ticket linkToDataSource
chat-with-pdf Conversation-scoped PDF file
chat-with-excel Conversation-scoped spreadsheet file

Naming

The keys are not uniform, and guessing at them is the most common cause of UPLOAD_FUNCTION_NOT_FOUND:

  • PDF is pdf-document — not pdf-file.
  • Word and PowerPoint are docx-file and pptx-file — not docx-document or pptx-document. Those do not exist.

Conversation-scoped types

chat-with-pdf and chat-with-excel back "chat with this document" flows. Pair them with isTemporary: true and a conversationId in stringifiedUniqueParameters, and the source is scoped to that conversation rather than added to the permanent knowledge base. See Access control and options.


Linked-source types

confluence and jira-ticket need credentials configured on the bot before ingestion will succeed. Without them the call is accepted and fails later during processing — visible as hasExhaustedRetries: true on getKnowledgebaseSources, not as an error from the mutation.

Every StudioX operation returns a response object carrying a status, a code and a human-readable message.

Branch on code. Display message. Never parse message.

Remember that these arrive with HTTP 200 — the failure is in the body. See Conventions and Errors.

Treat any code you do not recognise as a failure whenever status is not 200. Codes are added without notice.


Success

Code Operation
USERS_QUERY_SUCCESSFUL getUsers
CURRENT_USER_QUERY_SUCCESSFUL currentUser
GET_AI_ENGINE_VERSION_QUERY_SUCCESSFUL getAIEngineVersion
KNOWLEDGEBASE_LABELS_QUERY_SUCCESSFUL getKnowledgebaseLabels
USER_ADDED addUserToBusiness
UPDATE_SUCCESS updateUser
USER_DELETED deleteUser
BUSINESSES_QUERY_SUCCESSFUL getBusinesses
LABEL_CREATED addKnowledgebaseLabel — message carries the new label ID
LABEL_UPDATED / LABEL_DELETED updateKnowledgebaseLabel / deleteKnowledgebaseLabel
API_KEY_VALID verifyPersonalApiKey
PERSONAL_API_KEY_GENERATED generatePersonalApiKey
PERSONAL_API_KEY_DELETED deletePersonalApiKey
ADDED_TO_KNOWLEDGEBASE addKnowledgebaseSource — queued, not yet searchable
DOCUMENT_DELETED deleteKnowledgebaseSource
SUCCESS Generic success

getSystemHealthCheck is the odd one out: it returns code: "1", and the REST health check returns code: 0.


Authentication and authorization

Code Status Meaning Fix
UNAUTHORIZED 401 Key missing, invalid or revoked Check the header name and the key
NOT_AUTHORIZED 401 Authenticated, but not permitted The key's account needs a higher role
API_ACCESS_DENIED 401 Key valid, but not on this bot's API access list Add the account to the bot's API access — why
PERMISSION_DENIED 403 Role too low for this operation Use a business-admin key
USERS_ACCESS_DENIED 403 Not permitted to list these users Check linkedBusinessId
UNAUTHORIZED_BUSINESS_ACCESS 403 Key not linked to that business Use a business the key belongs to
ROLE_ESCALATION_DENIED 403 Cannot grant a role above your own Use a higher-role key
INSUFFICIENT_BUSINESS_AUTHORITY 403 Role too low for this target user Use a higher-role key
SYSTEM_USER_DELETION_FORBIDDEN 403 Platform-managed account Cannot be deleted over the API
API_KEY_GENERATION_FORBIDDEN 403 The business restricts who may mint API keys An administrator must grant API access
INVALID_API_KEY — verifyPersonalApiKey rejected the key Check the key
BUSINESS_API_ACCESS_DENIED 403 Not permitted to list these businesses Use a business the key belongs to

API_ACCESS_DENIED means the key is fine and the bot has not been told to trust it.


Quotas

All return status: 400. All are terminal — retrying will not clear them. The message states current usage against the ceiling; show it to the user.

Code Budget
TOKEN_LIMIT_EXCEEDED Tokens in a single request
MONTHLY_TOKEN_LIMIT_EXCEEDED Tokens this calendar month
STORAGE_LIMIT_EXCEEDED Knowledge base storage (GB)
DOCS_LIMIT_EXCEEDED Documents in the business
PAGES_LIMIT_EXCEEDED Document pages in the business
ERROR_CHECKING_USER_LIMITS Quota check itself failed — retry

Raising a ceiling is an administrator action. See Quotas.


Not found

Code Status Meaning
USER_NOT_FOUND 404 No such user
CURRENT_USER_NOT_FOUND 404 The key's own account is missing
CURRENT_LOGGED_IN_USER_NOT_FOUND 404 Same, during a delete
DELETE_USER_NOT_FOUND 404 Target user does not exist
BUSINESS_NOT_FOUND 404 No such business
BOT_NOT_FOUND 404 No such bot
INVALID_LINKED_BUSINESS_ID 400 Malformed business ID

Validation

Code Status Meaning
INVALID_EMAIL 400 Malformed email
DUPLICATE_USER_EMAIL 400 Email already in use
ROLE_DOWNGRADE_WARNING 400 Would downgrade an existing user
CANNOT_DELETE_YOURSELF 400 A key cannot delete its own account
USER_NOT_IN_BUSINESS 403 Target is not in the given business
DUPLICATE_USERNAME 400 Username already in use
USER_NOT_LINKED_WITH_ANY_BUSINESS 403 The key's account belongs to no business
LABEL_NOT_FOUND 404 No such label
TITLE_NOT_FOUND 400 addKnowledgebaseSource requires a title
FILE_NOT_FOUND 400 This dataSourceType expects a file
LINK_TO_DATA_SOURCE_NOT_FOUND 400 This type expects a linkToDataSource
PLAIN_TEXT_NOT_FOUND 400 This type expects a plainTextSource
UPLOAD_FUNCTION_NOT_FOUND 400 Unrecognised dataSourceType
PIPELINE_NOT_FOUND 400 No processing pipeline for this type on this bot
SOURCE_DECLINED_SKIPPED 200 Rejected by the bot's approval rules

Server

Code Status Retry
INTERNAL_SERVER_ERROR 500 Yes, with exponential backoff
ERR_ADDING_USER 500 Yes
ERR_TO_ADD_KNOWLEDGEBASE 500 Yes
API_KEY_VERIFICATION_ERROR — Yes

Only 500-class codes are worth retrying.


Chat API

The Chat API does not use this envelope. It returns HTTP 200 and streams failures as prose. See Chat API.

An API key carries its owner's identity. Every authorization decision is made against that user's role and business membership — a key is never a superuser.


Primary roles

A user has exactly one, listed here from most to least privileged.

Role Scope
business-super-admin A business hierarchy — a primary business and its children
business-admin One business: its users, bots and knowledge bases
business-support Support-level access within a business
user Ordinary end user

There is no viewer role.


Who can call what

Operation Minimum role
getSystemHealthCheck (none — unauthenticated)
GET /api/healthCheck/ (none — unauthenticated)
currentUser Any authenticated user
getAIEngineVersion Any authenticated user
getUsers business-admin
addUserToBusiness business-admin
deleteUser business-admin
addKnowledgebaseSource Bot upload access — see below
deleteKnowledgebaseSource Bot upload access
getKnowledgebaseSources Bot access
getKnowledgebaseLabels Bot access
getKnowledgebaseDataSourceTypes Any authenticated user
getAsyncTasksByOperationId business-admin
Chat API Any valid key, subject to the bot's access list

Two rules cut across all of it:

  • You cannot grant a role above your own — ROLE_ESCALATION_DENIED.
  • You cannot act outside your businesses — UNAUTHORIZED_BUSINESS_ACCESS.

Bot operations are gated twice

Knowledge base and chat operations check the caller's role and the bot's own API access list. The second check applies only to personal API keys — a signed-in browser session skips it entirely.

Each bot carries botAPIsAccess.usersRestriction:

Value Who may call the bot's APIs
businessUsers (default) Any user linked to the bot's business
(restricted) Only the explicit userEmails and teams on the bot's access list

The practical consequence, and a frequent support case: an administrator who manages a bot happily in the dashboard can still get API_ACCESS_DENIED from their own API key. The fix is in the bot's configuration, not the key.

It also means the API Workbench can succeed where your integration fails, because the Workbench uses your session. Always confirm an operation with your real key before automating it.


Designing an integration

  • Use a dedicated service account, not a person's key — it survives staff changes and limits exposure.
  • Give it the lowest role that works. Read-only integrations rarely need business-admin.
  • If it touches bots, add it to each bot's API access list explicitly, and expect API_ACCESS_DENIED until you do.
  • Keep provisioning keys (business-admin) separate from chat keys (user).

Version history

Oct 19, 2026

The StudioX GraphQL API guide, on the downloads page beside the Core API.

Downloads

FormatFileSizeSHA-256
Guide (PDF)studiox-api-user-guide.pdf2.4 MBf63b6fb76fed7935f5a23fb5734b17dc13601f7d82e31b6709e5691cfe6cd3d3

SHA256SUMS

Check the file is ours

Compare the file's SHA-256 with the one listed for it before you run it.

# macOS / Linux
shasum -a 256 <file>

# Windows (PowerShell)
Get-FileHash <file> -Algorithm SHA256

Related

  • StudioX Core API — Run your business on StudioX from your own code over HTTP: people and roles, assistants and what they know, chat, AI usage, tokens.
  • StudioX CLI — Run your business on StudioX from a terminal or a script: people and roles, assistants and what they know, chat, AI usage, tokens.