Calling an assistant via the API

The EasyRag REST API lets you query an assistant from any application or automation tool (n8n, Power Automate, etc.). Its interactive documentation (OpenAPI / Swagger) is available on every instance at /api/v1/docs.

1. Create an API key

In the administration area, open API keys (Administrator or Owner role) and create a key, with an expiration date if possible. It starts with er_ and is shown only once: store it in a secrets manager.

A key acts with all the permissions of the user who created it. For an integration, create a dedicated account whose role and accessible assistants are restricted to the strict minimum.

The key is sent in the Authorization: Bearer er_… or X-Api-Key: er_… header.

2. Ask a question

curl -X POST "https://<api-address>/api/v1/chatbots/<assistant-id>/chat/complete" \
  -H "Authorization: Bearer er_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "message": "What is the withdrawal period?" }'

Response (structure):

{
  "response": "You have 14 days from receipt [1].",
  "sessionId": "…",
  "conversationId": "…",
  "sources": [
    { "filename": "Terms-of-sale.pdf", "snippet": "…", "sourceUrl": null, "documentId": "…", "corpusId": "…" }
  ],
  "usage": { "promptTokens": 0, "completionTokens": 0, "totalTokens": 0 }
}

3. Continue the conversation

Send back the sessionId you received so that the assistant takes previous exchanges into account:

{ "message": "What about an in-store purchase?", "sessionId": "<received sessionId>" }

4. Get a structured response

With "responseFormat": "json", the assistant is asked to produce JSON. To enforce a specific schema, configure the JSON output format (with schema) in the assistant’s settings.

5. Stream the response

To display the response while it is being generated, use the Server-Sent Events stream:

GET /api/v1/chatbots/<assistant-id>/chat/stream?message=<question>&sessionId=<session>

Best practices

• Display the sources with the answer: that is what makes it verifiable.
• Handle 429 errors (rate limit) by retrying after a delay.
• Never put an er_ key in code that runs in the browser: for a website, use the widget.
• For n8n, a workflow template can be downloaded from the platform’s Tools page.