Account management for AI agents

A curated set of Unless REST API endpoints accepts API key authentication, which makes them usable by an AI agent acting on behalf of an account user - no interactive login required. This guide explains how to authenticate, which endpoints are available, and how to chain them to complete common account management tasks.

Authentication

Every request needs four headers:

Header	Value
x-api-key	An API key. Both the account-wide key and a personal key from the account settings work.
x-user-email	The email address of the user the agent acts on behalf of.
x-account-id	The account ID, found in the account settings.
x-website-id	The ID of the workspace (website) to operate on.

All endpoints are served from https://api.unless.com and prefixed with /api/v1. Requests and responses are JSON.

Example:

curl https://api.unless.com/api/v1/tasks?websiteId=<website-id> \
  -H "x-api-key: <api-key>" \
  -H "x-user-email: <user-email>" \
  -H "x-account-id: <account-id>" \
  -H "x-website-id: <website-id>"

Notes:

• Send either an API key or a JWT, never both. Requests carrying both an Authorization header and an x-api-key header are rejected.
• The permissions of the resolved user apply. A key only reaches the websites its user has access to.

Endpoint catalog

Full request and response details for each endpoint are in the REST API reference. This catalog tells an agent which endpoint fits which job.

Investigate an account

Endpoint	Use it to
GET /api/v1/tasks	List the account’s work items: knowledge suggestions, detected gaps, flagged conversations, sales signals.
GET /api/v1/ai/configuration	Inspect how the AI is configured: main language, product name, custom rules.
GET /api/v1/ai/training	See which knowledge sources the AI is trained on and how ingestions went.
GET /api/v1/audiences	List the visitor segments defined for the account.
GET /api/v1/personalizations	List the personalizations (experiences) running on a website.
GET /api/v1/help-center/publish-status	Check whether the help center is published, publishing or failed.
GET /api/v1/ai/quality/control	List the control questions the AI is scored against.
GET /api/v1/ai/quality/control/report	List quality control reports, or fetch one report’s per-question results with ?reportId=.

Act on an account

Endpoint	Use it to
PUT /api/v1/tasks	Change a task’s state (open, done, deleted), assign it, or edit it.
POST /api/v1/tasks	Create a new task for the account team.
POST /api/v1/ai/training/data	Ingest a website (or another source) so the AI learns its content.
POST /api/v1/help-center/publish	Publish the help center so content changes go live.
POST /api/v1/audiences	Create a new audience, or update an existing one.
POST /api/v1/ai/quality/control	Add or update a control question and its expected answer.
POST /api/v1/ai/quality/control/report	Start a quality control run that scores the AI against every control question. Returns the reportId to poll.

Ask the AI

Endpoint	Use it to
POST /api/v1/ai/query	Ask the account’s trained AI a question and get an answer in realtime.

Chaining endpoints

Most real tasks combine a read to establish context with one or more writes, followed by a read to verify the result.

Work through open tasks

1. GET /api/v1/tasks?websiteId=...&state=open to list what needs attention.
2. Investigate a task using the read endpoints, for example GET /api/v1/ai/training for a knowledge gap task.
3. PUT /api/v1/tasks with { "taskId": ..., "websiteId": ..., "state": "done" } once handled.

Ingest a website

1. GET /api/v1/ai/training to check whether the site is already a source.
2. POST /api/v1/ai/training/data with { "trainingData": { "accountId": ..., "websiteId": ..., "type": "url", "method": "all", "url": "https://www.example.com", "isPublic": true } }.
3. Poll GET /api/v1/ai/training and watch indexedUrlsCount and lastScanTimestamp to follow progress.

Publish the help center

1. GET /api/v1/help-center/publish-status to confirm no publish is running (state.runningJobId is null).
2. POST /api/v1/help-center/publish for a full publish, or with a partial scope for specific FAQs.
3. Poll GET /api/v1/help-center/publish-status until the job’s status is terminal.

Create an audience

1. GET /api/v1/audiences to inspect existing audiences and their rule format.
2. POST /api/v1/audiences with a name, a rule (JSON string) and a state.
3. GET /api/v1/audiences?ruleId=... to verify the result.

Score the AI with a quality control report

Generating a report costs one AI call per control question, so it is only available on the Enterprise, Flex, Fixed and Plus plans. On any other plan POST /api/v1/ai/quality/control/report answers 403.

1. GET /api/v1/ai/quality/control to see the control questions. A report scores every one of them, so add what is missing with POST /api/v1/ai/quality/control first.
2. POST /api/v1/ai/quality/control/report to start the run. It answers 400 when there are no control questions yet, and otherwise returns the reportId.
3. Poll GET /api/v1/ai/quality/control/report. The new report appears in the list once its first question has been scored, with processed counting up to totalQuestionsInReport.
4. GET /api/v1/ai/quality/control/report?reportId=... for the per-question results once processed equals totalQuestionsInReport.