API reference

Run the application and open the live API docs. OpenAPI JSON comes from the same registered Huma operations and Go types that handle requests. Use your application's host and port when they differ from localhost:8080.

There is no generation command or checked-in specification to maintain. After editing a route or request/response type, rebuild/restart the application and refresh the page. The document reflects that instance's enabled routes. HTTP_DOCS_ENABLED=false disables both URLs. The JSON endpoint is self-contained; the interactive page loads a pinned Scalar viewer from a CDN and needs network access.

Find and try an operation#

1. Start the application with the capabilities and dependencies you need.
2. Open /docs on that same instance and choose a tagged operation.
3. Inspect required fields, accepted values, successful statuses, and problem responses.
4. For a protected operation, supply your access token through the viewer's bearer authentication control.
5. Send the request, then copy its X-Request-ID response header when investigating the result.

Use a local or intended development instance when trying operations that write data. The viewer sends real requests; it is not a simulator. A docs page does not bypass authentication or enable a disabled capability.

To inspect the document without the interactive viewer:

curl --fail http://localhost:8080/openapi.json

Enable capabilities#

Business paths include the /api/v1 prefix.

Authentication also requires valid keys, mail and rate-limiter dependencies. Configuration validation reports missing requirements. Phone verification, Apple sign-in and SMS delivery are not implemented. Expo push is optional.

Use Authorization: Bearer <access_token> on protected operations. Send refresh tokens in the refresh body. User reads are self-service, notifications are recipient-scoped, and Media management authorizes the owner. Content reads require public visibility or a valid temporary link. Uploads default to public visibility. A successful registration does not guarantee completion of best-effort local welcome-event reactions. Email OTP sends return 202 for all addresses. OTP and social verification return 201 for a newly created account, or 200 for an existing account, with tokens and data.user. After either status, use data.user.profile_complete to decide whether to prompt for the name. Update it through PATCH /users/me; GET /users/me exposes the same completion state.

Change an endpoint#

1. Edit the Go input/output types and their Huma schema tags.
2. Register the typed handler once with huma.Register and huma.Operation.
3. Return response.OK, Created or Accepted with a typed result, or response.Error(ctx, err) for a service failure. Declare non-200 success statuses on the operation too. Rebuild/restart and refresh /docs.

Method, path, security, validation and schemas come from those registrations. Use explicit stable operation IDs when clients depend on them. Tests in this package exercise the live document, authentication, response schemas and concurrent first requests without application configuration or infrastructure.

Application success bodies contain typed data and optional operation-specific meta. Problems keep Huma's top-level error fields, errors list and optional meta. Use apperror.InvalidFields for multiple application validation messages. The generated body schemas contain neither request_id nor api_version; read X-Request-ID and X-API-Version response headers instead. Both headers also accompany 204 responses and file streams, which retain their native semantics.

For a deployment-specific snapshot, download /openapi.json with your preferred HTTP client. Health, metrics and the optional queue dashboard are standard HTTP infrastructure handlers outside the business OpenAPI document.

See handlers, requests and responses for the common patterns.

Keep runtime and OpenAPI aligned#

The usual route change has one source of truth:

Go request/response types + huma.Operation → route + validation + live OpenAPI

A few explicit declarations still matter:

A runtime response constructor cannot change the startup-time specification. Test both sides when adding status variants, streams, or custom headers. The response guide shows each shape.

Export a deployment snapshot#

For client generation or a reviewed release artifact:

curl --fail http://localhost:8080/openapi.json -o /tmp/go-modular-openapi.json

That file describes the instance you queried, including its enabled routes. It is an export, not a new hand-maintained source. Generating a client from it is a separate tool choice; the framework does not ship an automatic client pipeline.

Troubleshoot the reference#

The developer documentation website and /docs are different surfaces: this site explains how to use the framework; the live viewer describes HTTP operations registered by your running application. Continue with routing and HTTP tests.