HTTP API for integrations

The external API lets another program give the agent a task: your site's backend, a CRM, n8n or Make, your own bot, a background job. You send a message, Eggent runs it like an ordinary chat and returns the answer.

#Base URL

#Get a token

1. Open Settings → API.
2. Generate an external API token.
3. Store it in your system as a secret.

The token goes in the Authorization: Bearer <token> header. Never put it in code that runs in a browser: with it anyone can give the agent any task. On your own server you can set EXTERNAL_API_TOKEN instead of generating one; a token from settings takes precedence.

#Send a message

POST /api/external/message
Authorization: Bearer <token>
Content-Type: application/json

curl -X POST https://name.cloud.eggent.ai/api/external/message \
  -H "Authorization: Bearer $EGGENT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "crm:client-42",
    "projectName": "Sales",
    "message": "Write a short follow-up email based on the latest notes"
  }'

#Request fields

With no project, the message goes to the orchestrator.

#Response

{
  "success": true,
  "sessionId": "crm:client-42",
  "reply": "Hi Anna! …",
  "context": {
    "activeProjectId": "sales",
    "activeProjectName": "Sales",
    "activeChatId": "0a2f…",
    "activeChatTitle": "Call with Anna",
    "currentPath": ""
  },
  "chatChanged": false,
  "switchedProject": null,
  "createdProject": null
}

If the agent switched or created a project during the run, you see it in switchedProject and createdProject. chatChanged is true when the conversation is now in a different chat than before this message — the agent moved it — and activeChatTitle names that chat.

#How sessionId works

For each sessionId, Eggent remembers the current project, the current chat and the working folder. Reuse the same sessionId and the agent continues the same conversation, with its history. A new sessionId is a new conversation.

Good keys: telegram:<user-id>, crm:<client-id>, slack:<channel>:<thread>, job:daily-report.

#Streaming the answer

Add Accept: text/event-stream and the answer comes as a stream of events (SSE) — handy for showing the text as it is written. Each event is JSON on a data: line:

If the client disconnects mid-answer, the work is not interrupted: the agent finishes it and the result is saved in the chat.

#Sending a file

POST /api/external/media-message
Authorization: Bearer <token>
Content-Type: multipart/form-data

The same fields as /message, plus file and kind (document, photo, audio, video, voice, file). The file is saved to the chat's attachments and the agent sees it. A voice note (kind=voice) is transcribed to text first.

curl -X POST https://name.cloud.eggent.ai/api/external/media-message \
  -H "Authorization: Bearer $EGGENT_API_TOKEN" \
  -F "sessionId=crm:client-42" \
  -F "message=List every deadline in this contract" \
  -F "kind=document" \
  -F "file=@./contract.pdf"

#Errors

#Tips

• Call the API only from a server, and only over HTTPS.
• Set a generous timeout: a complex task can take several minutes. Or use streaming.
• One real conversation, one sessionId.
• A message that starts with @ and a project's name hands the task to that project, as in the app: the project works in a chat of its own and its answer is part of the reply. See Projects.
• API answers spend balance just like the chat, and always run in full mode.