What Are the Best Practices for Using the EquilAI REST API?

Keep your API key on the server, start one conversation per user session and reuse its id, upload attachments before referencing them, and back off when you hit a rate limit. Those four habits cover most of what separates a solid integration from a flaky one. The rest of this guide goes through each area in a little more depth.

Where Should Your API Key Live?

On your server, and nowhere else. The key is a secret credential for your bot, so never ship it in browser JavaScript or inside a mobile app binary, where anyone can extract it. Your frontend talks to your backend, and your backend talks to EquilAI, sending the key either as an x-api-key header or as an apiKey field in the JSON body.

Create and manage keys under Dashboard, in the API section. If a key ever leaks, revoke it there and issue a new one.

How Should You Manage Conversations?

Start a conversation once per user session with POST /api/chat/start, keep the returned conversationId, and pass it with every message. This is what gives the assistant memory: send messages without a conversation id and every question lands without context.

Two useful properties of the lifecycle:

• Nothing is stored when you start a conversation. Sessions only begin to count when the first message is sent, so creating a conversation eagerly at page load costs nothing.
• One conversation belongs to one end user. Do not share a conversation id between users, or their contexts will bleed into each other.

How Do Attachments Work?

Upload first, reference second. Send the file as multipart/form-data to the upload endpoint, take the attachment id from the response, and include it in the attachmentIds array of your next message. Images and PDF documents are supported, up to 10 MB per file and up to four attachments per message. A message may even be attachments-only, with an empty text body, when the file is the question.

How Should You Handle Errors and Limits?

Treat status codes as instructions:

• A 4xx response means the request itself needs fixing: a missing key, a malformed body, or a file that is too large. Retrying the same request will not help.
• A rate-limit response means slow down. Retry with exponential backoff instead of hammering the endpoint, and keep a sensible timeout on your side.
• Log the response body on failures. The API returns human-readable error messages that usually name the exact problem.

What Happens to Personal Data in Messages?

Messages that arrive through the API pass through server-side PII redaction before they are stored and before they reach the language model. Email addresses, payment card numbers, national identity numbers and phone numbers are replaced with neutral placeholders automatically. You do not need to build a scrubbing layer in front of the API, although you should still avoid sending data the bot does not need.

Where Is the Full Reference?

The complete endpoint documentation, with request and response examples, lives in the REST API docs, and the key setup is covered under Authentication.