AI Assistant Fundamentals

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

MethodEndpointWhat it does
POST/responsesCreate a response by submitting a prompt
GET/responses/{response_id}Retrieve a previously created response
POST/responses/{response_id}/cancelCancel a response that is currently in progress
GET/responses/{response_id}/input_itemsList the input items for a response

Conversations

MethodEndpointWhat it does
POST/conversationsCreate a conversation
GET/conversations/{conversation_id}Retrieve a conversation
DELETE/conversations/{conversation_id}Delete a conversation
GET/conversations/{conversation_id}/itemsList the items in a conversation

Function-Archive sources

MethodEndpointWhat it does
GET/function-archive-sourcesList 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.

FieldRequiredWhat it does
modelYesAlthough required, Global Relay selects the model to be used. The response always reports server-selected rather than mirroring what was sent.
inputYesThe question: a string, or an array containing exactly one message.
conversationNoThe conversation id to be used for continued conversations. If not included, one is created automatically and the id is returned.
toolsNoInclude the tools field to identify the Function and Archive you can access.
reasoningNoDetermine whether AI Assistant composes answers using a reasoning model.
streamYesSet 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.