API reference — AtlasLaunch AI

Basics

Base address https://assistant.atlasvoice.cloud. JSON in, JSON out.
Authenticate with your secret key: Authorization: Bearer ala_live_…. Keep it on your server.
Errors are { "error": { "code", "message" } } with a matching HTTP status. Codes are stable; messages say what to do.
Optional X-AtlasLaunchAI-Client: yourapp/1.0 for your own statistics.

Connect a site

POST /v1/projects/register

curl -X POST https://assistant.atlasvoice.cloud/v1/projects/register \
  -H 'Content-Type: application/json' \
  -d '{"platform":"custom","site_url":"https://example.com","email":"[email protected]"}'

# → { "api_key": "ala_live_…", "project_id": 12, "plan": "free", "approval": "approved" }

One project per site domain. If the email already has an account, the key waits until the owner approves it (an email link). GET /v1/usage returns the month’s answers used and left.

Index: send your content

Route	Body / answer
`POST /v1/index/upsert`	`{ items: [ { id, url, title, type, modified?, text, facts?: { price, stock, on_sale, categories[] } } ] }`, 1–100 items, 4 MB. Answers counts and the index status.
`POST /v1/index/delete`	`{ ids: [] }` (up to 500) or `{ all: true }`.
`GET /v1/index/status`	`{ items, passages, pending, updated, limit }`

POST /v1/index/upsert

{ "items": [ {
  "id": "101", "url": "https://example.com/shop/blue-mug/",
  "title": "Blue ceramic mug", "type": "product",
  "text": "A hand-glazed blue mug that holds 350 ml. Dishwasher safe.",
  "facts": { "price": 24.5, "stock": "instock", "on_sale": true }
} ] }

Unchanged items are skipped, unchanged passages keep their processing, and facts never cause re-processing. Not counted as answers; capped per plan (Free 2,000, Pro 20,000 items) and at 60 changes a minute per site.

Sitemap reading

Route	Body / answer
`POST /v1/index/crawl`	`{ sitemap_url?, interval_hours?, enabled? }`: default `/sitemap.xml` on your site, every 24 hours (6–168). Reads it now.
`GET /v1/index/crawl`	Settings and the last result: pages, fetched, unchanged, skipped, failed, removed.
`DELETE /v1/index/crawl`	Stops re-reading (pages already read stay).

Our reader identifies itself as AtlasLaunchAI/1, follows sitemap indexes, stays on your host, respects robots.txt and noindex, and fetches only pages whose <lastmod> changed. Pages it reads have ids starting with u:; content you push is never removed by it.

Public site key

Route	Body / answer
`POST /v1/site-key`	`{ origins?: [], rotate?: true }` → `{ site_key: { public_key, allowed_origins } }`. Default origins: your site with and without `www.`; `rotate` replaces the key at once.
`GET /v1/site-key`, `DELETE /v1/site-key`	Read it, or switch it off.

The public key works only from its allowed origins, with limits per address and per visitor, and is billed to the same site. (Also available as /v1/public-key.)

Ask

POST /v1/ask

{ "q": "Do you ship to Canada?",
  "history": [ { "role": "user", "text": "Hi" } ],
  "page": { "id": "101", "type": "product" },
  "lang": "en" }

// → 200
{ "answered": true,
  "text": "Yes. Delivery to Canada takes five to eight days.",
  "sources": [ { "id": "21", "title": "Shipping", "url": "https://example.com/shipping/" } ],
  "answers": 1 }

q up to 500 characters; the last 6 turns of history; optional page, lang and actions (the site’s own actions, see the SDK).
answered: false: your site doesn’t say. A greeting comes with suggestions, “what do you sell?” with categories. An action (go, list with items, filtered by query or category and sorted by sort, read_page, summary, shop and your own actions) comes as { type, args }.
One answer per successful call. Browsers call POST /public/v1/{public key}/ask with the same body.

Errors

Status	Code	Meaning
400	`empty_question`, `invalid_items`, `invalid_actions`…	A bad request; the message names the field. Not counted.
401	`missing_api_key`, `invalid_api_key`, `invalid_public_key`	No key, or a revoked one.
403	`approval_required`, `origin_not_allowed`, `plan_limit_reached`	Waiting for the owner; a website not allowed for the public key; the index is full.
429	`quota_exceeded`, `rate_limited`	The month’s answers are used up (with `usage.resets_at`), or too many at once (`Retry-After`). Never billed as overage.
502 / 503	`model_unavailable`, `server_busy`, `service_unavailable`	Temporary; not counted. Point the visitor to your site search.