Skip to main content

AI Answers API reference

This page describes how to send a question to the AI Answers API and how to read the answer that comes back.

Before you start, turn the API on and copy the API address, tenant ID and project ID from the Access tab. If the API requires a key, you also need one of the project's API keys. See Set up API access for AI Answers.

Send a question

Send a POST request to the project's API address, with a JSON body. Use these headers:

Header

Value

Content-Type

application/json

Authorization

Bearer followed by your API key. Only send this header when the API is set to API key required. Leave it out when the API is Public.

The body has these fields. All of them are required, except history:

Field

Value

tenantId

The tenant ID from the Access tab.

projectId

The project ID from the Access tab.

language

The language code of the content to answer from. For example, en.

message

The question, as plain text.

history

Earlier questions and answers in the conversation, oldest first. Each item has a role, either user or assistant, and a content string. Up to 20 items.

The API doesn't store conversations. To ask a follow-up question, send the earlier questions and answers in history.

For example:

curl -N -X POST "<API address>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API key>" \
  -d '{
    "tenantId": "<tenant ID>",
    "projectId": "<project ID>",
    "language": "en",
    "message": "Can I publish it to more than one channel?",
    "history": [
      {"role": "user", "content": "How do I publish a topic?"},
      {"role": "assistant", "content": "To publish a topic, add it to a publication and select Publish."}
    ]
  }'

Read the answer

The answer comes back as a stream of server-sent events, so your application can show the text while it is still being written. Each event is a line that starts with data:, followed by a JSON object. Its type field says what kind of event it is:

Type

What it contains

answer

The first event. answerId identifies this answer.

text

A piece of the answer in content. Join the pieces in the order they arrive, with nothing between them. A piece can end in the middle of a word.

sources

The topics the answer is based on, in sources. Each has a url and a title. The url is relative to the address of your published portal, so add the portal address in front of it to make a link.

error

Something went wrong while the answer was being written. Treat the answer as failed.

done

The last event. It can carry a reason, described below.

When the answer is complete, the done event has no reason. When it has one, the reason tells you why the answer ended:

Reason

Meaning

no_match

Nothing in the published content answers the question.

refused

The question was declined. Don't show any text that arrived before this event.

not_available

Answers can't be given right now. Try again later.

For example:

data: {"type": "answer", "answerId": "<answer ID>"}

data: {"type": "text", "content": "To publish a topic, add it to "}

data: {"type": "text", "content": "a publication and select Publish."}

data: {"type": "sources", "sources": [{"url": "en/publish/publish-a-publication", "title": "Publish a publication"}]}

data: {"type": "done"}

An answer usually takes 5 to 20 seconds to finish streaming.

Errors

Errors are returned as an HTTP status code before any events are sent:

Status

Meaning

401

The API key is missing or not accepted.

403

Forbidden.

404

The API is turned off for this project, or nothing has been published from it yet.