OrdstageDocs

Resources

Assistants

List assistants, publish, pause and resume them, send test messages in the sandbox, and manage the web pages they learn from.

Assistants are built in Studio. The API lets your systems operate them: see their state, publish the current setup, pause and resume them, try them in the sandbox, and keep their knowledge pages fresh.

Scope Lets a key
assistants:read List assistants, get one with its lifecycle, list its knowledge sources.
assistants:write Publish, pause, resume, send test messages, add, refresh and remove knowledge pages.

Changes are made as the key's creator, who must still be an owner, admin or manager (or hold the assistants permission); otherwise the answer is 403 key_creator_not_allowed.

Publishing, pausing and resuming

POST /v1/assistants/{assistant_id}/publish does what Publish does in Studio and needs an Idempotency-Key. It is refused with Studio's reason while setup is incomplete, for example assistant_release_not_ready, brand_identity_unapproved or flow_validation_failed.

curl -X POST https://api.ordstage.com/v1/assistants/6f1c2e4a-8b3d-4c5e-9f70-1a2b3c4d5e6f/publish \
  -H "Authorization: Bearer $ORDSTAGE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

pause stops the assistant answering (new messages go to the team); resume makes it answer again, and is refused (assistant_not_resumable) until the current setup is published and nothing blocks it.

Events: assistant.published, assistant.paused, assistant.resumed.

Test messages

POST /v1/assistants/{assistant_id}/test_messages works with test keys only (live keys answer 409 test_key_required). The message runs against the sandbox's sample assistant, like the test chat in Studio: nothing reaches a customer, and it uses the sandbox's AI allowance. Pass the returned session_id with the next message to continue the conversation.

{ "message": "Do you open on Fridays?" }

Knowledge pages

GET /v1/assistants/{assistant_id}/knowledge_sources lists what the assistant learns from (pages, files, sheets). With the API you can add a public web page, refresh a source, or remove one:

  • POST .../knowledge_sources with {"url": "https://…", "name": "Prices"} adds a page and reads it right away (status goes from processing to ready, or error). Publish the assistant for customers to get it.
  • POST .../knowledge_sources/{source_id}/refresh reads it again; the previous text stays in use until then.
  • DELETE .../knowledge_sources/{source_id} stops using it at once.

Only public http/https pages are read. Adding and refreshing pages isn't available in the sandbox.