Send messages and manage conversations using APIs

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.

This guide is for people building integrations. Use the downloadable OpenAPI definitions for exact request fields, response formats and attachment requirements.

Choose an API

The Messages API creates a temporary conversation for each request. The Conversations API keeps conversation history between requests.

Before you start

1. Open the assistant for editing.
2. Under Automation & API, select API Keys.
3. Find the Assistant ID and Base URL under API Essential Information.
4. Select Download OpenAPI Definition under Messages API or Conversations API, depending on your task.
5. Prepare the credentials your integration will use.

If 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.

Authenticate your requests

The 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.

For a personal access token to work:

• The token must include the assistant.
• The token owner must still have access to the assistant.
• The assistant must allow personal access tokens.
• The token must not have expired or been revoked.

See Create and manage personal access tokens for token instructions.

Keep credentials private. Do not put real keys or tokens in prompts, shared examples, screenshots or support requests.

Send a one-off message

Use the Messages API when you need a response to a standalone request.

1. Open the Messages API OpenAPI definition.
2. Build a request using the documented message fields.
3. Include any optional attachments in the format specified by the definition.
4. Send the request to the documented endpoint, using your base URL and credentials.
5. Read the assistant’s response.

The API creates a temporary conversation, processes the request and returns the assistant’s response.

Use the Conversations API instead if your next request needs earlier messages as context.

Start and continue a conversation

Replace {assistantId} and {conversationId} in the paths below with the relevant IDs. Use your base URL before each path.

Start a conversation

1. Send a POST request to:
   /api/assistants/{assistantId}/conversations
2. Include a message to run the first turn, or send an empty JSON object ({}) to create a conversation without a message.
3. Keep the conversation ID returned by the API for subsequent requests.
4. Check the response for pendingApprovals and expiresAtUtc.

Use the OpenAPI definition for the exact message structure and the response field containing the conversation ID.

Send a follow-up message

1. Send a POST request to:
   /api/assistants/{assistantId}/conversations/{conversationId}/messages
2. Include your next message using the documented request format.
3. Read the response and check for pending approvals.

The assistant uses earlier messages in that conversation as context. You do not need to start a new conversation for each follow-up.

Handle tool approvals

Some MCP tools require approval before they can run.

When the assistant requests one of these tools, the turn pauses and the response lists the tool call in pendingApprovals.

1. Check the response for pending approvals.
2. Review each tool call and decide whether to approve or deny it.
3. Send your decision to:
   /api/assistants/{assistantId}/conversations/{conversationId}/approvals
   using the POST method.
4. Pass the same modelSettings as the message request.
5. Check the continued response for any further pending approvals.

Use the OpenAPI definition for the approval identifiers and decision fields.

Do not send another message while approvals are pending. New messages are rejected with HTTP 409 until none remain.

Read or delete a conversation

Read the transcript

Send a GET request to:

/api/assistants/{assistantId}/conversations/{conversationId}

This returns the transcript so far, with user and assistant turns as text.

Reading the transcript does not extend the conversation’s expiry.

Delete a conversation

Send 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.

Manage expiry and concurrent requests

Conversation expiry

A conversation expires after 24 hours without a message.

• Every message extends the expiry.
• The response returns the current expiry as expiresAtUtc.
• Reading the transcript does not extend the expiry.
• Expired conversations are deleted, along with files they produced.

Use expiresAtUtc to track the current expiry rather than assuming it remains unchanged.

Concurrent requests

Only one message can be in progress in a conversation at a time.

Wait for the current message to finish before sending another message to the same conversation. A second concurrent message is rejected with HTTP 409.

Troubleshoot requests

A message returns HTTP 409

Check whether:

• Another message is still being processed in the same conversation.
• The conversation has pending tool approvals.

Wait for processing to finish, or resolve the pending approvals, before sending another message.

A personal access token stops working

Check that the token has not expired or been revoked, still includes the assistant, and its owner retains access.

Also check that Allow personal access tokens remains turned on for the assistant. Turning it off immediately blocks personal access tokens from calling that assistant.

A conversation has expired

Start a new conversation. Do not rely on an expired conversation to retain earlier messages or generated files.