Run an Assistant Query via API

There are automations designed to work via API with the Assistants or act as a user in a Space. This includes Agents of Unique or self-created Agents that are configured to be in a space, e.g., running a query in the internal Knowledge space. Here, we describe the required automation.

For this, a conversation-centered approach is used, similar to how the frontend of the chat interacts within a space with the agents.

The protocol follows these steps:

Create a prompt message to an Assistant in a space.
This generates a chat session.
Poll the generated chat until the answer is received.
Send follow-up prompts as needed.

If you encounter issues during development with these endpoints, it is useful to observe how the frontend interacts via GraphQL with the system during chat prompting.

Alternatively, contact your designated Customer Success Manager or Data Science Consultant at Unique.Getting a Token for auth

Token of a user / service-user which has admin role assigned → <yourToken>
The base URL of your application → <baseUrl>

To get the token and the URL check this: How to get a Token for our APIs

Running a query against the Assistant (Agent)

Make sure you are using the correct <AssistantId> (also known as spaceId), which starts with assistant_ and corresponds to the space where the agent is defined.

The Prompt (<Your Prompt>) is the message you wish to send to the Assistant.

Below is the full cURL request to send a message.

curl 'https://gateway.<baseUrl>/chat/graphql' \
  -H 'authorization: Bearer <yourToken>' \
  -H 'content-type: application/json' \
  --data-raw $'{"query":"mutation MessageCreate($chatId: String, $assistantId: String, $input: MessageCreateInput\u0021, $translationInput: TranslationOneToOneCreateInput) {\\n  messageCreate(\\n    chatId: $chatId\\n    assistantId: $assistantId\\n    input: $input\\n    translationInput: $translationInput\\n  ) {\\n    id\\n    text\\n    role\\n    chatId\\n    createdAt\\n    messages {\\n      id\\n    }\\n  }\\n}","variables":{"chatId":null,"input":{"text":"<Your Prompt>","role":"USER"},"assistantId":"<AssistantId>"},"operationName":"MessageCreate"}'

This will return a <chatId>, which is required to fetch the response to the Prompt and to send follow-up Prompts to that ID.

The response:

{
    "data": {
        "messageCreate": {
            "id": "msg_sd68kvjw3ti5gvwp1rfvtmng",
            "text": "test",
            "role": "USER",
            "chatId": "chat_vowfz1qg0gkxqhcq9dk5f9ao", <-- THIS IS THE CHATID
            "createdAt": "2025-03-02T21:03:34.040Z",
            "messages": []
        }
    }
}

This request runs a full Assistant asynchronously, making it non-blocking and returning immediately.

To fetch the result after streaming, a second endpoint is required.

Polling the Agent for the completed answer

The answer can be polled at intervals from the endpoint. Use reasonable polling times depending on the Agent you are using, as the response will be provided in a message thread.

To avoid excessive system load, use a minimum interval of 3 seconds between requests.

Messages can be retrieved using the following query:
<ChatId> refers to the ID received in the response to the message creation.

curl 'https://gateway.<baseUrl>/chat/graphql' \
  -H 'authorization: Bearer <yourToken>' \
  -H 'content-type: application/json' \
  --data-raw $'{"query":"query PaginatedMessage($chatId: String\u0021, $take: Int, $skip: Int, $orderBy: [MessageOrderByWithRelationInput\u0021], $includeDebugInfo: Boolean\u0021 = false) {\\n  paginatedMessage(chatId: $chatId, take: $take, skip: $skip, orderBy: $orderBy) {\\n    nodes {\\n      id\\n      text\\n      originalText\\n      role\\n      chatId\\n      createdAt\\n      references {\\n        id\\n        name\\n        sequenceNumber\\n        url\\n      }\\n      stoppedStreamingAt\\n      feedback {\\n        positive\\n        text\\n        additionalInfo\\n      }\\n      previousMessage {\\n        id\\n      }\\n      gptRequest @include(if: $includeDebugInfo)\\n      debugInfo @include(if: $includeDebugInfo)\\n      assessment {\\n        explanation\\n        id\\n        isVisible\\n        label\\n        title\\n        status\\n        type\\n        messageId\\n      }\\n    }\\n    totalCount\\n  }\\n}","variables":{"chatId":"<ChatId>","take":20,"skip":0,"orderBy":[{"createdAt":"desc"}],"includeDebugInfo":true},"operationName":"PaginatedMessage"}'

The answer to the query will look like this.

{
    "data": {
        "paginatedMessage": {
            "nodes": [
                {
                    "id": "msg_t45vv6ogm3wzv0wjuyn94w1q", < --- NEEDED FOR FOLLOW UP QUESTIONS
                    "text": "Hello! How can I assist you today?",< --- HERE IS THE ANSWER
                    "originalText": "Hello! How can I assist you today?", 
                    "role": "ASSISTANT",
                    "chatId": "chat_mi872wqujf15f081q3kau3zt",
                    "createdAt": "2025-03-02T20:15:09.056Z",
                    "references": [],
                    "stoppedStreamingAt": "2025-01-02T20:15:09.914Z", < --- THIS NEEDS TO BE SET SO ITS FINISHED
                    "feedback": null,
                    "previousMessage": {
                        "id": "msg_i5eg1hso4sk87568jjg0g6dv"
                    },
                    "gptRequest": null,
                    "debugInfo": null,
                    "assessment": []
                },
                {
                    "id": "msg_i5eg1hso4sk87568jjg0g6dv",
                    "text": "test",
                    "originalText": null,
                    "role": "USER",
                    "chatId": "chat_mi872wqujf15f081q3kau3zt",
                    "createdAt": "2025-01-02T20:15:08.999Z",
                    "references": [],
                    "stoppedStreamingAt": null,
                    "feedback": null,
                    "previousMessage": null,
                    "gptRequest": [
                        {
                            "role": "system",
                            "content": "You are ChatGPT, a large language model trained by OpenAI\nCurrent date: 2025-03-02."
                        },
                        {
                            "role": "user",
                            "content": "test"
                        }
                    ],
                    "debugInfo": {
                        "assistant": {
                            "id": "assistant_scadkouuf8vz4plcixihj0bt",
                            "name": "UQ - ⚡️ Chat with GPT-4o"
                        },
                        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
                        "chosenModule": "ExternalKnowledge",
                        "userMetadata": {
                            "email": "andreas@unique.ai",
                            "lastName": "Hauri",
                            "userName": "andreas@unique.ai",
                            "firstName": "Andreas",
                            "displayName": "Andreas Hauri",
                            "targetRegion": "Switzerland",
                            "targetContinent": "Europe"
                        },
                        "toolParameters": {},
                        "timeToStreamInMs": 90,
                        "chosenModuleResponse": "System: Directly chat with LLM or using Translation module"
                    },
                    "assessment": []
                }
            ],
            "totalCount": 2
        }
    }
}

where the <stoppedStreamingAt> of the first message is the one you wish to wait for it to be set. As long as it is null it is not finished with the generation.

Once this is set the first messges <text> will contain the answer of the Agent.

Send a follow up Prompt

For a follow up message use the following query:
<FOLLOWUP> is the prompt to be sent
<ChatId> remains the same chat as before
<PreviousMessageId> is the message id of the message before and can be found in the anwer above. It is the last messaes <id>
<AssistantId> remains the same as in the messages before.

curl 'https://gateway.<baseUrl>/chat/graphql' \
  -H 'authorization: Bearer <yourToken>' \
  -H 'content-type: application/json' \
  --data-raw $'{"query":"mutation MessageCreate($chatId: String, $assistantId: String, $input: MessageCreateInput\u0021, $translationInput: TranslationOneToOneCreateInput) {\\n  messageCreate(\\n    chatId: $chatId\\n    assistantId: $assistantId\\n    input: $input\\n    translationInput: $translationInput\\n  ) {\\n    id\\n    text\\n    role\\n    chatId\\n    createdAt\\n    messages {\\n      id\\n    }\\n  }\\n}","variables":{"chatId":"<ChatId>","input":{"text":"<FOLLOWUP>","role":"USER","previousMessage":{"connect":{"id":"<PreviousMessageId>"}}},"assistantId":"<AssistantId>"},"operationName":"MessageCreate"}'

The same polling pattern for the answer now is applied again. As soon as the messages contain the <stoppedStreamingAt> the answer can be read.

Author	@Andreas Hauri

Public Documentation

Run an Assistant Query via API

The protocol follows these steps:

Running a query against the Assistant (Agent)

Polling the Agent for the completed answer

Send a follow up Prompt

Related content