StudioX Core API

Run your business on StudioX from your own code over HTTP: people and roles, assistants and what they know, chat, AI usage, tokens.

For developers and administrators connecting their own systems and scripts to StudioX. The OpenAPI file loads into Postman, Swagger UI or a client generator.

Updated Oct 19, 2026

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.

Version history

Oct 19, 2026

First release: people and roles, assistants and their documents, chat, AI usage and scoped tokens over HTTP at /api/v1.

Downloads

FormatFileSizeSHA-256
Guide (PDF)core-api-guide.pdf375 KB1d9beaf52f6560b95195f3aeb62365e4c3b235472b7c52b86b3c43d2590fc4f1
OpenAPI 3.1 (JSON)core-api-openapi.json24 KB90e58b76aaec280e80d92031bbbb0aadfb0ff8e83e95a3166b95cc1b72e0dd8b

SHA256SUMS

Check the file is ours

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

# macOS / Linux
shasum -a 256 <file>

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

Related

  • Missions API — Run, manage and build missions from your own code over HTTP: tokens, every endpoint, errors, jobs, worked examples.
  • StudioX CLI — Run your business on StudioX from a terminal or a script: people and roles, assistants and what they know, chat, AI usage, tokens.
  • StudioX API User Guide (GraphQL) — Call the StudioX GraphQL API with your personal API key: people and roles, knowledge sources, streaming chat, the API workbench, every error code.