Quickstart

Get started with Copilot via API in minutes. This guide walks you through the basic flow of generating a response using Copilot via API.

Basic Flow

Conceptually, you will:

1. Retrieve available assistants.
2. Create a thread, which represents a conversation between a user and an assistant.
3. Attach one or more user messages to this thread.
4. Run the thread to generate an assistant message.
5. Optionally retrieve all messages in the thread.

For additional operations (e.g. deleting threads), refer to the API Reference.

Step 1: Retrieve Available Assistants

Copilot via API offers various assistants specialized in different domains such as Tax, HR, and Sustainability. Use this endpoint to retrieve all available assistants and their associated metadata structure.

curl --request GET \
  --url https://api.haufe.ai/agents/v1/assistants \
  --header 'api-key: <API_KEY>'

The response contains the list of available assistants and their metadata structures. For full data type definitions, refer to the API Reference.

Step 2: Create a Thread

To start a conversation with an assistant, create a new thread:

curl --request POST \
  --url https://api.haufe.ai/agents/v1/threads \
  --header 'content-type: application/json' \
  --header 'api-key: <API_KEY>' \
  --data '{
    "assistant_id": "<ASSISTANT_ID>",
    "user_id": "<USER_ID>",
    "title": "First Thread Example"
  }'

The response contains the id of the created thread, referred to as thread_id in the following steps.

Step 3: Attach User Messages

After creating a thread, attach one or more user messages to it:

curl --request POST \
  --url https://api.haufe.ai/agents/v1/threads/:thread_id/messages \
  --header 'content-type: application/json' \
  --header 'api-key: <API_KEY>' \
  --data '{
    "role": "user",
    "content": "<Your Message Content>"
  }'

• Replace :thread_id with the id from the Create a thread response.
• You can add multiple user messages by calling this endpoint multiple times.
• Each message must include role (must be "user") and content (max 30,000 characters).
• Only user messages are allowed. Attempting to add assistant messages manually will result in an error.

Step 4: Generate an Assistant Message (Run)

Trigger generation of an assistant response by running the thread:

curl --request POST \
  --url https://api.haufe.ai/agents/v1/threads/:thread_id/run \
  --header 'content-type: application/json' \
  --header 'api-key: <API_KEY>' \
  --data '{
    "meta_data": {
      "user_data": {
        "licence": "<LicenseId>"
      }
    }
  }'

• This endpoint shares rate limits with other answer-generation operations (/run, /run/stream). See Rate Limits.
• To receive the response incrementally, use the streaming variant: POST /agents/v1/threads/:thread_id/run/stream.

The response contains an AssistantMessage with the generated answer and corresponding metadata.

Step 5: Retrieve Messages

You can retrieve all messages in a thread, including user and assistant messages:

curl --request GET \
  --url https://api.haufe.ai/agents/v1/threads/:thread_id/messages \
  --header 'api-key: <API_KEY>'

The endpoint is paginated and returns messages sorted by creation time (newest first).

Next Steps