docs
/
AppEngine API

API reference and discovery

Discover the current deployment's API, read operation contracts and generate a client.

AppEngine serves its API reference from the running backend. Use the deployment's base URL, not the Studio URL. Discovery routes are public and tenant-free; a route discovered there still has its own authentication rules when called.

NeedGET route
Browser reference/documentation
Conventional browser aliases/api-docs, /docs, /swagger (302 redirects)
Agent entry point/llms.txt
All endpoints as a Markdown index/documentation.md
Search/documentation/search?q=...&limit=20
One operation/documentation/endpoint?method=POST&path=...
One operation as JSONSame route with format=json
Navigation index/documentation/index.json
A section/documentation/tag/:slug.md or :slug.json
Complete OpenAPI/openapi.json or /documentation-json

Search, then read the exact operation

Set API to your deployment origin without a trailing slash:

curl -sS --get "$API/documentation/search" \
  --data-urlencode 'q=repository find' --data-urlencode 'limit=5'

The result contains query, count and results. Each hit includes detail and section URLs. Follow these instead of inventing a tag slug or substituting a real record ID into the documentation path. Endpoint lookup uses the documented route template and HTTP method, not an operation ID:

curl -sS --get "$API/documentation/endpoint" \
  --data-urlencode 'method=POST' \
  --data-urlencode 'path=/repository/find/{datatype}'

The default detail format is Markdown. Add --data-urlencode 'format=json' for the operation and its schema components. Download the full document only when you need code generation or an import:

curl -fsS "$API/openapi.json" -o appengine-openapi.json

The browser page loads its index and sections on demand. Fetching its HTML alone is not an endpoint inventory; use Markdown or JSON for tools that do not execute JavaScript.

Diagnose discovery failures

Missing q, or missing method/path, returns 400. An unknown operation or section returns 404. An index or full document that has not initialized returns 503. Search defaults to 20 results and caps a requested limit at 100. These are reference-service failures, not evidence that your tenant credential is wrong.

Check the installed deployment when generating clients: source changes may be newer than that deployment. Examples on this page describe the inspected controller contract and are not a report of a live request.

Turn discovery into an implementation

Start the written AppEngine developer course for identity setup, executable examples, business APIs and acceptance exercises. The API reference lesson includes a small Node discovery tool and a method for comparing an operation with a client wrapper.

The API directory groups useful section links. The running deployment's index is authoritative for its current section names and counts. Source reviewed on 7 October 2026 may be newer than the deployment you are calling.

Generate a client from the selected deployment

Download appengine-openapi.json using the command above, then generate the language client against that saved document. For example, with OpenAPI Generator installed:

openapi-generator-cli generate \
  -i appengine-openapi.json -g java -o ./appengine-java

Review the generated authentication headers, request types and response envelopes before use. Generation covers the documented HTTP surface; it does not implement provider SDKs, Socket.IO event handling, OIDC middleware exchanges or business outcome verification. Exercise an authenticated read, a denied read and a controlled write/readback before adopting the generated client in your application.

How the reference is assembled

AppEngine combines Nest route discovery, controller metadata and registered API specifications into its served description. Controllers in the current tree do contain Swagger decorators; descriptions and examples can also be supplied by the documentation registry. A route being present does not prove that every DTO, example or client wrapper matches its delegated service implementation.

When code and documentation disagree, trace the controller into the service and record the concrete mismatch. The developer lessons identify examples of this, including environment-domain field names and SDK wrapper paths. Keep the deployed contract, source revision and verified request together instead of copying an old endpoint count into an integration guide.

MCP is a separate discovery/execution surface; see MCP server. API discovery remains useful when an agent needs the underlying HTTP contract.