Documentalist

This document describes how to use the DIMARC API to interact with the /documentalist endpoint. This endpoint allows you to send requests to a documentalist agent with a question, specific instructions, and a conversation history.

POST /v2/documentalist

Prerequisites

An active DIMARC account.
Administrator status in your organization.
A configured “Documentalist” type agent.
Your agent must have visibility configured to Public or Organization to be usable via the API.
Your authentication token x-api-key (see Retrieving Your Authentication Token)

Retrieving an agent’s ID

Each agent has a unique ID. To retrieve the ID of the Documentalist agent, go to your dashboard:

Click on your profile icon in the top right corner, then go to the Organization > API section or by clicking here
In the References of your agents section, you can retrieve the ID of the Documentalist agent you want to use.

Communicate with your Documentalist

To communicate with the Documentalist agent, send a POST request to the /v2/documentalist/<agent_id> endpoint with your authentication token.

Request Parameters

Parameter	Type	Description
`query`	string	The question or query to address to the documentalist agent
`instructions`	array	List of specific instructions to guide the agent’s response (optional)
`historic`	array	History of previous conversations (optional)
`thread_id`	string	36-character UUID to maintain a persistent conversation history (optional)

Request Example

curl --location 'https://api.dimarc.ai/v2/documentalist/<agent_id>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <your_api_key>' \
--data '{
    "query": "What does Dimarc do?",
    "instructions": ["Add 🌈 in your responses"],
    "historic": []
}'

Response Format

The response is a raw text stream (ReadableStream), always over HTTP 200.

On success, the stream directly contains the agent’s answer:

Dimarc is an artificial intelligence platform specialized in creating customized AI agents.

On internal failure (processing queue unavailable, timeout, agent unable to answer), the same apology text is returned, still over HTTP 200 — there is no way to distinguish a real error from a normal response without inspecting the content:

Désolé, je ne peux pas vous donner de réponse pour le moment.

Only two cases short-circuit the stream with a real error HTTP status, as raw text (no JSON envelope):

Status	Case
404	Agent not found, wrong type, private, or outside your organization
404	Provided `thread_id` does not match a thread for this agent

Managing conversation history

To maintain a consistent context throughout the exchanges, you have two options:

Option 1: Using the `thread_id` parameter

You can pass a thread_id (36-character UUID) to automatically maintain a persistent conversation history on the server side. This allows you to preserve context between multiple API calls without having to manually manage the history.

Option 2: Manually providing the history

You can include the history of previous conversations in the historic parameter. This allows the agent to understand the complete context of the exchange.

History Format

The history must be provided as an array of objects alternating between user messages and agent responses:

"historic": [
  {
    "role": "user",
    "content": "What does Dimarc do?"
  },
  {
    "role": "assistant",
    "content": "🌈 Dimarc is an artificial intelligence platform specialized in creating customized AI agents. 🌈"
  }
]

Limitations and considerations

Response times may vary depending on the complexity of the query and the information sources that the Documentalist agent decides to use.
The sources used by the Documentalist agent are not returned in the response at the moment.

Support and assistance

For any questions regarding the Documentalist API, contact our support team at contact@dimarc.fr