Your app's API

How the routes you write become the public, contract-validated, SDK-generating gateway surface — capabilities, the router, CRUD, errors, caching, cross-app calls and the published OpenAPI document.

Declaring the surface

Capabilities

define vs implement, the capability key vs the URL, and why a route maps to /v1/<path>.

Capability reference

Every field of a capability entry — route, parameters, request, response, responses, cache and the rest.

The published OpenAPI document

/v1/openapi.json — the single source the SDKs, the Explorer and MCP all read.

Writing the handler

The router

createApp, routes, the request context, the health route, and 405 vs 404.

CRUD

mountCrud — the five standard routes, pagination bounds and per-column filters.

Pagination and filtering

The page envelope, and why an undeclared parameter strands callers on page one.

Errors

HttpError and its helpers, the constraint-violation mapping, and declaring responses.

Caching

The cache block, vary_by, invalidate_on and the X-Cache header.

Across the app boundary

Calling another app

The capability grant, the headers to forward, and whose fault a 4xx is.

Overriding a capability

implement and compatible — taking over another app's route for your tenants.

Nothing your function answers is reachable from outside until a capability declares it. That one rule is the whole of this group.

A capability is one typed HTTP operation. You declare it in manifest.capabilities.json, and the platform serves its route verbatim under the gateway's /v1 prefix, validates every request against the contract before your function is invoked, and publishes the same declaration into the tenant's OpenAPI document — and from there into the generated SDKs, the API Explorer and the MCP server.

text

manifest.capabilities.json ──► routes under /v1 ──► /v1/openapi.json ──► SDKs · API Explorer · MCP
src/main.js                ──► the handler behind each route

So your API has two halves, and both have to agree:

The declaration — what the contract says the operation takes and returns. This is also your documentation; there is no second place to fix a wrong description.
The handler — the code the router dispatches to. Written with createApp, mountCrud and your own routes.

The trap in that split is worth stating up front: the declared contract must never be stricter than the handler. The gateway validates against the declaration, so a required field your handler treats as optional turns a working request into a 400 your code never sees.

In this group

Capabilities — the model: define, implement, the key, the route.
Capability reference — every field, in a table.
The router — createApp, the request context, route matching.
CRUD — mountCrud and the five standard routes.
Pagination and filtering — the list envelope and its parameters.
Errors — returning the right status, and declaring it.
Caching — the gateway response cache.
Calling another app — the outbound half.
Overriding a capability — implement.
Tags — grouping your operations.
The published OpenAPI document — what everything downstream reads.

API usage — the headers, errors, rate limits and pagination conventions every call to api.revenexx.com follows, yours included.
The typed client — what your handlers read and write.
Verifying live — calling your own capability through the gateway once it is deployed.