Endpoints

Endpoints map a path and method to a response. A database-backed response references a schema with schema:; a static one uses inline:.

List endpoint

Reference a schema with type: array to return every record from its table.

- path: /users
  method: GET
  response:
    type: array
    schema: User
  status: 200

curl http://localhost:3000/users
# => [{"id": 1, "name": "Example 1", ...}, ...]

Single item

Use :id in the path for parameter-based lookups. Akuma queries the database for that specific ID and returns 404 if it doesn't exist.

- path: /users/:id
  method: GET
  response:
    schema: User
  status: 200

curl http://localhost:3000/users/1
# => {"id": 1, "name": "Example 1", ...}

curl http://localhost:3000/users/999
# => 404 {"error": "Not found"}

Mutations

The examples above read data. A schema-backed endpoint declared with POST, PATCH/PUT, or DELETE changes its table instead. See Mutations.

How the table is resolved

The endpoint serves the table belonging to the schema it references, not the path. schema: User always reads from the users table, whatever the path is named. (Schema names become tables by snake_casing and pluralizing. See Data models.)

Static endpoints

For endpoints that don't touch the database, return fixed JSON with inline:. See Static responses.

- path: /health
  method: GET
  response:
    inline:
      status: ok
  status: 200

Common mistakes

Referencing a schema that does not exist

An endpoint's schema: must name a schema defined under schemas:. A typo or a missing definition fails at startup:

Error: Endpoint GET /x references unknown schema 'Ghost'. Define it under `schemas:`.