With the Core API you run your business on StudioX from your own code: you add people and set their roles, make assistants and give them documents to know, send them questions, and read what your AI use costs. Everything is plain HTTPS and JSON, with a token in one header.
The address is your StudioX address followed by /api/v1, for example
https://www.studiox-ai.com/api/v1. On your own installation it is your own host.
The examples below use two shell variables:
export STUDIOX=https://www.studiox-ai.com/api/v1
export TOKEN=sx_pat_... # your token
Your token
You can call the API with any of these:
| You send | What it is | What it can do |
|---|---|---|
sx_pat_… |
A personal token you made | What you can do, narrowed to the scopes you chose |
sx_svc_… |
A service token an administrator made | What its service user can do, in one business, narrowed to its scopes |
| Your personal API key | Profile → StudioX API Key | Everything you can do |
Send it as Authorization: Bearer <token>. Your personal API key also works without Bearer,
exactly as it does with the GraphQL API.
A token never gives you more than your role. A token with admin held by someone who is not an
administrator changes nothing they could not change already.
Scopes
| Scope | Lets the token |
|---|---|
read |
Read you, your business, its people, assistants, documents, conversations, usage, your tokens |
chat |
Send messages to assistants |
manage |
Make, change and delete assistants; add and remove documents |
admin |
Change business settings; add people, change roles, remove people; make tokens |
Make a token
Make your first token with your personal API key:
curl -s -X POST $STUDIOX/tokens \
-H "Authorization: Bearer $PERSONAL_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"label":"reporting script","scopes":["read"],"expiresInDays":90}'
The answer holds the token in token. This is the only time you see it: store it now. Leave out
expiresInDays for a token that lasts until you revoke it.
A token can make another token only if it holds admin, and the new token gets no scope the first
one lacks.
Service tokens
A service token acts as one member of your business — usually a user you set up for the purpose,
such as robot@yourcompany.com — and only in that business. You make it as an administrator; it
keeps working when you leave; every administrator of the business can see it and revoke it.
curl -s -X POST $STUDIOX/tokens \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"kind":"service","label":"nightly sync","scopes":["read","manage"],"serviceUser":"robot@yourcompany.com"}'
The service user must already be a member of the business (see Add someone). The token stops working if they are removed from it.
See and revoke tokens
curl -s $STUDIOX/tokens -H "Authorization: Bearer $TOKEN" # yours
curl -s "$STUDIOX/tokens?kind=service" -H "Authorization: Bearer $TOKEN" # the business's service tokens
curl -s -X DELETE $STUDIOX/tokens/<id> -H "Authorization: Bearer $TOKEN"
A revoked token is refused from that moment.
You and your business
curl -s $STUDIOX/me -H "Authorization: Bearer $TOKEN"
curl -s $STUDIOX/business -H "Authorization: Bearer $TOKEN"
/me says who the token acts as, your role, your businesses, and the token's scopes.
Every call acts in your primary business. If you belong to more than one, add
?businessId=<id> (or the header X-Business-Id) to act in another. A service token acts in its
own business only.
Change business settings
You change the sign-in policy and whether new conversations are private, as an administrator with
admin. Send only what changes:
curl -s -X PATCH $STUDIOX/business \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"sessionTimeoutMinutes":480,"lockConversationsByDefault":true}'
| Setting | What it does |
|---|---|
sessionTimeoutMinutes |
Signs people out after this many minutes; 0 removes the limit |
dailyForceLogoutEnabled |
Makes everyone sign in again once a day |
dailyForceLogoutMode |
fixed-time (at a time of day) or rolling-24h |
dailyForceLogoutTimeOfDay, dailyForceLogoutTimezone |
With fixed-time: "02:00" and "America/Los_Angeles" |
lockConversationsByDefault |
New conversations are readable only by the person who started them and those they share with |
The business's name and contact details are changed in Studio.
People
You list, add, change and remove the people in your business as an administrator. The same rules apply as in Studio: a business administrator cannot add or promote anyone to business super administrator, and cannot change a business super administrator.
curl -s "$STUDIOX/users?search=lee&page=1&pageSize=50" -H "Authorization: Bearer $TOKEN"
Add someone
curl -s -X POST $STUDIOX/users \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"email":"lee@yourcompany.com","name":"Lee Park","role":"user"}'
Roles: business-super-admin, business-admin, business-support, user (the default).
outcome in the answer says what happened:
outcome |
Meaning |
|---|---|
added (201) |
A new account was made with that role |
joined (200) |
They already had an account; they joined your business and kept their role |
already-member (200) |
They were already in your business |
They sign in with their email address. The call sends them nothing.
Change a role
curl -s -X PATCH $STUDIOX/users/<userId> \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"role":"business-support"}'
Remove someone
curl -s -X DELETE $STUDIOX/users/<userId> -H "Authorization: Bearer $TOKEN"
They lose your business; their account stays.
Assistants
curl -s $STUDIOX/assistants -H "Authorization: Bearer $TOKEN"
curl -s $STUDIOX/assistants/<id> -H "Authorization: Bearer $TOKEN"
Make one
curl -s -X POST $STUDIOX/assistants \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"IT Help","role":"Answers questions about laptops, printers and accounts"}'
Optional: specialization, slug (the last part of its address; default from the name),
domain (the address people open it at; default your business's address), loginSetting
(company to need sign-in, the default; "" for open).
Change or delete one
curl -s -X PATCH $STUDIOX/assistants/<id> \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"IT Help Desk"}'
curl -s -X DELETE $STUDIOX/assistants/<id> -H "Authorization: Bearer $TOKEN"
Deleting answers 202: the assistant and its knowledge are removed in the background.
What an assistant knows
An assistant's knowledge is the documents you give it.
# What it has, and whether each is ready
curl -s $STUDIOX/assistants/<id>/knowledge -H "Authorization: Bearer $TOKEN"
# Upload a file
curl -s -X POST $STUDIOX/assistants/<id>/knowledge \
-H "Authorization: Bearer $TOKEN" \
-F file=@printer-guide.pdf -F title="Printer guide"
# Add text, or a web page
curl -s -X POST $STUDIOX/assistants/<id>/knowledge \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"title":"Office hours","text":"The help desk is open 8am to 6pm Pacific."}'
curl -s -X POST $STUDIOX/assistants/<id>/knowledge \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"url":"https://intranet.yourcompany.com/it/faq"}'
# Remove one
curl -s -X DELETE $STUDIOX/assistants/<id>/knowledge/<documentId> -H "Authorization: Bearer $TOKEN"
A new document answers 202 and is processed in the background. Its status in the list goes
from processing to ready (or failed, or pending-approval when your business reviews new
documents first). PDF, Word, PowerPoint, Excel, audio and video files are read for what they
contain; text files are added as text.
Chat
curl -s -X POST $STUDIOX/assistants/<id>/chat \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"message":"How do I add a printer on a Mac?"}'
{ "conversationId": "6ad5…", "assistantId": "6ad4…", "reply": "Open System Settings…", "status": "completed" }
Send conversationId back to continue the same conversation. To see the reply as it is written,
add "stream": true (or Accept: text/event-stream); you get server-sent events:
stream:connected (with conversationId), stream:text (each piece), stream:text:end (the
whole reply), stream:error, stream:done.
curl -N -X POST $STUDIOX/assistants/<id>/chat \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"message":"Summarise the printer guide","stream":true}'
Read back your conversations:
curl -s $STUDIOX/assistants/<id>/conversations -H "Authorization: Bearer $TOKEN"
curl -s $STUDIOX/conversations/<conversationId>/messages -H "Authorization: Bearer $TOKEN"
If the assistant limits who may call it through the API (its API access setting), a token for
anyone else is refused with 403.
Usage and cost
As a business administrator you read what AI use cost over a period, in total, by day and by assistant:
curl -s "$STUDIOX/usage?from=2026-10-01&to=2026-10-31&timezone=America/Los_Angeles" \
-H "Authorization: Bearer $TOKEN"
Without dates you get the last 30 days. Amounts are in cents.
When something is refused
Every refusal has the same shape:
{ "error": "This token is not allowed \"manage\". Make a token with that scope.",
"code": "scope_missing", "scope": "manage" }
code |
Status | What to do |
|---|---|---|
unauthorized |
401 | The token is missing, unknown, revoked or expired: make a new one |
scope_missing |
403 | Make a token with the scope in scope |
forbidden |
403 | Your role, the business's API access setting, or the assistant's, does not allow it; reason names the rule |
not_found |
404 | Check the id; things in another business read as not found |
invalid_request |
400 | The message says which field |
conflict |
409 | It is in a state that refuses this; the message says why |
rate_limited |
429 | Wait the seconds in Retry-After |
upstream_error |
502 | The assistant could not answer; the message says why |
internal |
500 | Retry; report it with the time if it repeats |
A token has 600 requests a minute; a chat message counts as 5.
The full list
GET $STUDIOX/openapi.json (no token needed) is the OpenAPI 3.1 description of every endpoint.
It loads into Postman, Swagger UI or a client generator. The studiox command-line tool does
everything in this guide from a terminal.