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, and a Static API that hosts the front end calling all of it. 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.

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

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 — 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