title: "StudioX API" subtitle: "User Guide" cover: true
Contents
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 noBearerprefix - 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
- Building an integration → Authentication, then Conventions and Errors
- Managing users → Administration
- Loading documents → Knowledge Base
- Chat client → Chat API
- Exploring the schema → API Workbench
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
Authorizationentirely. It readspersonal-api-keyand nothing else. If you send your key asAuthorizationto/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.
getSystemHealthCheckandGET /api/healthCheck/are unauthenticated — they return200with no header at all, and they return exactly the same200for 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
linkedBusinessIdor 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.
generatePersonalApiKeyreturns it once, inapiKey, 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
messagestrings. - Treat unknown
response.codevalues as failures whenstatusis not200, 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
200with no key, a valid key or a garbage key. To check a key, usecurrentUser.
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 |
keywordis required and accepts an empty string; omitting it is a request-level error, not a default.sortFielddoes not acceptcreatedAt.
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
isOwnerfield. - The limit fields are strings, not integers —
"100000", not100000. - 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: truecannot be undone over the API. Default tofalseunless 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_DENIEDhere, 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 themessagestring — do not do that.messageis prose and is free to change.
A
200here 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. IfpendingReasonislimit_exceeded, an administrator must raise the cap; see Quotas.hasCompleted: truewithhasExhaustedRetries: 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,messageis the ID and nothing else:{"data":{"addKnowledgebaseLabel":{"status":200, "message":"68aa019574cd7aa7055c5e20","code":"LABEL_CREATED"}}}Read it only when
codeisLABEL_CREATED; on failuremessagecarries an error string instead. This is the one place in the API where parsingmessageis 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, notAuthorization. It is the only StudioX surface that does.Authorizationis 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, noerrorsarray, and no machine-readable failure flag in the stream.
?streaming=truedoes not behave this way — it returns real401and403responses. 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, noevent:lines and no blank-line record separators, soEventSource,sseclient-pyand other standard SSE clients will not parse it. Read it as newline-delimitedprefix:payloadframes, 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.
400for a missing user message,401for missing authentication,403with{"code": "SIGNIN_REQUIRED"}when the bot requires sign-in,404when the bot cannot be resolved. Auth failures are not streamed as content. - Standard SSE framing, so
EventSource,sseclient-py,httpx-sseand 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
responseobject 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
addKnowledgebaseSourcecan work here and returnAPI_ACCESS_DENIEDfrom 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 |
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— notpdf-file. - Word and PowerPoint are
docx-fileandpptx-file— notdocx-documentorpptx-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_DENIEDuntil you do. - Keep provisioning keys (
business-admin) separate from chat keys (user).