Use Theta Assist’s APIs to send requests to an assistant from an external application or automation. Choose the Messages API for a one-off request, or the Conversations API when follow-up messages need the context of earlier messages.
\nThis guide is for people building integrations. Use the downloadable OpenAPI definitions for exact request fields, response formats and attachment requirements.
\n| Your task | \nAPI to use | \n
|---|---|
| Send a standalone request that does not need earlier messages as context. | \nMessages API | \n
| Send follow-up messages that build on earlier messages. | \nConversations API | \n
The Messages API creates a temporary conversation for each request. The Conversations API keeps conversation history between requests.
\nIf your requests use a personal access token and need an external service, such as Microsoft 365, sign in to that service through the assistant’s tools in Theta Assist before using the API.
\nThe Conversations API uses the same integration API key as the Messages API. Send the key in the Api-Key header.
The Conversations API also accepts a personal access token in that header. When you use a personal access token, the conversation runs as the token owner, using their connected accounts.
\nFor a personal access token to work:
\nSee Create and manage personal access tokens for token instructions.
\nKeep credentials private. Do not put real keys or tokens in prompts, shared examples, screenshots or support requests.
\nUse the Messages API when you need a response to a standalone request.
\nThe API creates a temporary conversation, processes the request and returns the assistant’s response.
\nUse the Conversations API instead if your next request needs earlier messages as context.
\nReplace {assistantId} and {conversationId} in the paths below with the relevant IDs. Use your base URL before each path.
POST request to:/api/assistants/{assistantId}/conversations{}) to create a conversation without a message.pendingApprovals and expiresAtUtc.Use the OpenAPI definition for the exact message structure and the response field containing the conversation ID.
\nPOST request to:/api/assistants/{assistantId}/conversations/{conversationId}/messagesThe assistant uses earlier messages in that conversation as context. You do not need to start a new conversation for each follow-up.
\nSome MCP tools require approval before they can run.
\nWhen the assistant requests one of these tools, the turn pauses and the response lists the tool call in pendingApprovals.
/api/assistants/{assistantId}/conversations/{conversationId}/approvalsPOST method.modelSettings as the message request.Use the OpenAPI definition for the approval identifiers and decision fields.
\nDo not send another message while approvals are pending. New messages are rejected with HTTP 409 until none remain.
Send a GET request to:
/api/assistants/{assistantId}/conversations/{conversationId}
This returns the transcript so far, with user and assistant turns as text.
\nReading the transcript does not extend the conversation’s expiry.
\nSend a DELETE request to:
/api/assistants/{assistantId}/conversations/{conversationId}
This ends the conversation and deletes its messages, files and generated artefacts. Save anything your integration needs before deleting it.
\nA conversation expires after 24 hours without a message.
\nexpiresAtUtc.Use expiresAtUtc to track the current expiry rather than assuming it remains unchanged.
Only one message can be in progress in a conversation at a time.
\nWait for the current message to finish before sending another message to the same conversation. A second concurrent message is rejected with HTTP 409.
Check whether:
\nWait for processing to finish, or resolve the pending approvals, before sending another message.
\nCheck that the token has not expired or been revoked, still includes the assistant, and its owner retains access.
\nAlso check that Allow personal access tokens remains turned on for the assistant. Turning it off immediately blocks personal access tokens from calling that assistant.
\nStart a new conversation. Do not rely on an expired conversation to retain earlier messages or generated files.
\n","description":"Choose the Messages API for one-off requests or the Conversations API for follow-up messages. Learn how to authenticate requests, handle tool approvals, read and delete conversations, and manage expiry.","isMarkdown":false,"publishedOnUtc":"2026-10-28T23:54:52.5248562","modifiedOnUtc":"2026-10-28T23:10:09.0003924"}