The AI Assistant API is composed of the following core concepts:
- Response: One complete interaction, which includes a question and an answer. Although AI Assistant may take several reasoning steps and/or Archive searches to create a response, these equal one response.
- Conversation: An ordered history of your responses for a specific question. By passing the same conversation id in each response, the context is available in the conversation across follow up questions.
- Item: A single typed piece of content inside a response: a question, an answer, a reasoning step, or a record of a tool that ran it.
- Source reference: A citation that refers to the archived message that supports an answer.
- Archive and Function: The combination that determines which data a question runs against.
Response ids (resp_…) and conversation ids (conv_…) are stable and safe to store. Item ids inside a response are not stable. The same item can carry a different id depending on whether it was read from the live stream or from a later retrieval.
API resources and endpoints
The AI Assistant API is accessible at the base URL https://ai.api.globalrelay.com/v1 with three resource paths:
- Responses: Create, retrieve, and manage answers to your questions.
- Conversations: Create, retrieve, and manage conversations.
- Function-Archive sources: List the Archive and Function pairs available to the authenticated user.
Responses
| Method | Endpoint | What it does |
|---|---|---|
| POST | /responses | Create a response by submitting a prompt |
| GET | /responses/{response_id} | Retrieve a previously created response |
| POST | /responses/{response_id}/cancel | Cancel a response that is currently in progress |
| GET | /responses/{response_id}/input_items | List the input items for a response |
Conversations
| Method | Endpoint | What it does |
|---|---|---|
| POST | /conversations | Create a conversation |
| GET | /conversations/{conversation_id} | Retrieve a conversation |
| DELETE | /conversations/{conversation_id} | Delete a conversation |
| GET | /conversations/{conversation_id}/items | List the items in a conversation |
Function-Archive sources
| Method | Endpoint | What it does |
|---|---|---|
| GET | /function-archive-sources | List the available Functions and Archives for the authenticated user |
Asking a question
The following table outlines the optional and required fields to include in a question to AI Assistant.
| Field | Required | What it does |
|---|---|---|
model | Yes | Although required, Global Relay selects the model to be used. The response always reports server-selected rather than mirroring what was sent. |
input | Yes | The question: a string, or an array containing exactly one message. |
conversation | No | The conversation id to be used for continued conversations. If not included, one is created automatically and the id is returned. |
tools | No | Include the tools field to identify the Function and Archive you can access. |
reasoning | No | Determine whether AI Assistant composes answers using a reasoning model. |
stream | Yes | Set to true, which returns answers incrementally in real-time, rather than waiting for the entire answer to finish. |
The request body must be under 1 MB and the question must be under 28,000 characters.
Receiving an answer
Once you send a question, the following is returned in the answer:
- An identifier
- A status
- The conversation it belongs to
- The list of items AI Assistant produced
- Token usage
- If applicable, an error field if something went wrong
The original question is NOT included in the answer.
Streaming
Every question you send is returned with a streaming answer:
- Text displays incrementally as it is generated.
- Reasoning steps and Archive searches surface as they happen.
- Citations appear just before the answer is fully complete.
If you lose the network connection, you cannot reconnect to the stream in progress. However, the answer is not lost and keeps running on the Global Relay side, with the finished answer being retrieved afterwards using the response id.
Querying the Archive
When you ask a question about archived data, the following are factored into the answers:
Archive and Function scope
Every question you ask is run against one Archive and Function pair, which determines the data AI Assistant is allowed to view.
- If the requester has access to only one pair, it is automatically applied to the request if none are specified. You do not need to specify the pair in the request, which covers the majority of users.
- If the requester has access to more than one pair, you must include the applicable Archive and Function pair to use. Otherwise, the request is rejected and the requester is asked to specify which pair to use.
For details on how to locate your Archive and Function pair, see Getting Started.
Tools
For every question you ask of the archived data, AI Assistant uses a fixed, permitted set of tools, with Archive search being the primary one.
Source references
For each answer you receive, the sources, or citations, identify which part of the answer came from which archived message. These sources persist, so when you retrieve or reference a response, it returns the same sources as the original.