API documentation

altengine exposes several data-plane services over a single REST/JSON API: a Search API for full-text search, a Channel API for realtime pub/sub, a Datastore API for JSON document storage with a query engine, an Auth API that gives your app's end users accounts and identity tokens, a Blob API for files, a Functions API for the server-side logic that has to run inside the trust boundary, a Containers API for the long-running work that will not fit in a function, an Automation API for the work that is not reachable from the internet at all — desktop applications and firewalled portals on your own machines, a Static API that hosts the front end calling all of it, a Mailbox API that gives your app or agent email addresses, and a Tasks API that queues work for a function, a channel or a webhook and retries it until it is done. There is also an MCP server, so an AI agent can build on it directly. Search and Channel are faithful revivals of the retired App Engine APIs — your queries, field types and schemas carry over, and what you rewrite is the call layer — and Datastore follows the same App Engine–style shape.

Base URL

All API requests go to a single host over HTTPS:

https://api.altengine.net

The console — where you create instances, mint API keys, browse data, and see usage — lives separately at https://console.altengine.net.

Authentication

Every data-plane request is authenticated with an organization API key, passed as a bearer token:

Authorization: Bearer ae_yourkeyid.your-api-key-secret

The examples read it from $ALTENGINE_API_KEY, the variable the altengine CLI reads too.

Create keys in the console. A key belongs to your organization and is granted access to one or more service instances at a specific level. Keep keys secret — they carry the access below and should never ship in client-side code. For browser pub/sub, mint a short-lived, channel-scoped subscriber token instead of exposing your API key.

Revoking a key, or narrowing its grants, takes effect within about a minute, not instantly: until then some requests may still be accepted with the old access.

Rotate a key in the console to replace its secret while keeping its name and access. You choose how many days (0–30) the old secret keeps working; 0 stops it within about a minute. Rotating again before then ends the previous old secret at once. Only the member who created a key can rotate it; anyone else can create a new key with the same access from the same dialog, then revoke the old one.

A request may also be authenticated with an end-user identity token issued by the Auth API, in the same Authorization: Bearer header. Such a token carries one of your app's users rather than your organization, reaches only the instances your access rules name, and has those rules applied to every row it reads or writes — which is what lets a browser call Datastore and Channel with no backend of your own. The Auth API's own endpoints are public and need no key at all.

Grant levels

Audit log

Every organization has an audit log, under Audit log in the console. Owners can read it; members cannot. It records:

• every change made in the console, and every attempt refused for lack of permission;
• every MCP tool call that changes something, reveals a webhook secret or reaches an enrolled machine, under the key or the person who connected;
• console sign-ins, failed password sign-ins, sign-outs and password changes;
• changes altengine staff make to your organization.

Each entry has the time, who, the action, what it applied to, the IP address and the user agent. Request bodies are never stored, only the names of the fields that were sent. /v1 requests are not recorded.

Entries are kept for 1 year by default. An owner can change that under Settings → Audit log, from 90 days to 7 years; shortening it deletes older entries at once. Export to CSV or JSON from the log page.

Instances

You provision named instances of each service in the console — for example a search instance catalog or a channel instance live. The instance name is the first path segment after the service:

/v1/search/{instance}/...
/v1/channel/{instance}/...
/v1/datastore/{instance}/...
/v1/auth/{instance}/...

Search instances are further divided into indexes, and optionally namespaces (multi-tenancy) — see the Search API reference. Datastore instances hold namespaces of document collections — see the Datastore API reference. An auth instance holds your app's end-user accounts and the access rules that scope them — see the Auth API reference.

Instances have a Region setting (default auto, placed near first use), a placement hint that cannot move anything already placed:

• Auth, Blob, Static, Containers, Mailbox, Tasks — chosen when you create the instance, and fixed after. For Containers it places the instance's job tracking, not where jobs run.
• Search, Datastore, Channel, Automation — set any time in Settings; it places what the instance creates after that (an index, a namespace, a channel, a newly enrolled machine's connection).

Quickstart

Index a document and search it (an index is created on first write):

curl -X POST https://api.altengine.net/v1/search/catalog/ns/_default/idx/films/documents \
  -H "Authorization: Bearer $ALTENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"documents":[{"id":"f1","fields":[{"name":"title","type":"text","value":"Up in the Air"}]}]}'

curl -X POST https://api.altengine.net/v1/search/catalog/ns/_default/idx/films/search \
  -H "Authorization: Bearer $ALTENGINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"title:air"}'

Errors

Errors use standard HTTP status codes and a consistent JSON body:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "document not found"
  }
}

Reference