API reference

Eloqra exposes a small REST API for provisioning accounts and managing projects programmatically — handy for AI agents and scripted setups. All endpoints live under the /v1 base and return a JSON envelope.

Base URL#

bash

https://api.eloqra.app/v1

Every successful response is wrapped in an envelope with a message and a data payload:

json

{
  "message": "Success",
  "data": { }
}

Authentication#

Authenticated endpoints require two headers: your account ID and an API key. You'll find both in the dashboard under Settings → API.

http

x-eloqra-account-id: YOUR_ACCOUNT_ID
x-api-key: YOUR_API_KEY

Requests missing either header, or with an invalid key, return 401 Unauthorized. The one exception is agent-init below, which is public so an agent can create an account before any key exists.

POST`/v1/auth/agent-init`

Public. Start an account from just an email — used by AI agents to provision Eloqra before a key exists. Rate limited per IP and per email.

Body

Name	Type	Description
emailrequired	string	The account email. Disposable email domains are rejected.

Example

bash

curl -X POST https://api.eloqra.app/v1/auth/agent-init \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com" }'

Response — new account

For a brand-new email, Eloqra creates the account, issues an API key, and emails a claim link. The plaintext key is returned once — store it.

json

{
  "message": "Success",
  "data": {
    "accountId": "...",
    "apiKey": "...",
    "claimRequired": true,
    "expiresInDays": 3
  }
}

Response — existing account

If the email already belongs to a real account, no key is issued — the agent should ask the user to paste their existing key from Settings → API.

json

{
  "message": "Success",
  "data": {
    "claimRequired": false,
    "accountExists": true,
    "message": "Account already exists. Paste your API key from Settings → API to continue."
  }
}

GET`/v1/me`

Return the authenticated account's ID and email. Useful for verifying credentials.

Response

json

{
  "message": "Success",
  "data": { "accountId": "...", "email": "you@example.com" }
}

GET`/v1/projects`

List the projects on your account, most recent first.

POST`/v1/projects`

Create a new project. All fields are optional; a slug is generated from the business name if you don't pass one.

Body

Name	Type	Description
businessName	string	Used to generate a slug when slug is omitted.
slug	string	Preferred URL slug. Must not be a reserved slug.
website	string	Your site URL. Normalized to https.
headline	string	Optional headline for the project's public page.
description	string	Optional description for the public page.

GET`/v1/projects/:id`

Fetch a single project you own by its ID.

GET`/v1/projects/:id/embed-snippet`

Return the ready-to-paste embed snippet for a project.

Response

json

{
  "message": "Success",
  "data": {
    "projectId": "...",
    "widgetUrl": "https://chat.eloqra.app/eloqra-chat.js",
    "script": "<script> ... </script>"
  }
}

The script value is the same one-line async snippet shown in the dashboard — it sets window.ELOQRA_CHAT_CONFIG with your project ID and loads eloqra-chat.js. No container element is needed; paste it before the closing </body> tag and the chat bubble appears on every page.