Source document · API/docs/GETTING_STARTED.md

Getting started with the API

This guide gets a developer from an API URL to a successful authenticated request. The Go API is the source of truth for user identity, listing eligibility, prices, permissions, and booking/payment state. Android and the admin web app are clients of this service.

Environments and base URL

Use the origin of the API server, then append the versioned route. The production host is chosen during deployment, so examples use placeholders rather than inventing a domain.

The API process serves plain HTTP. Production HTTPS terminates at a reverse proxy in front of it. Mobile release builds require an HTTPS API URL.

Check the service

curl -i http://localhost:8080/health
curl -i http://localhost:8080/ready
curl -i http://localhost:8080/api/v1

/health checks that the process responds. /ready is the deployment readiness gate and checks PostgreSQL in staging and production. /api/v1 reports the API name and version. /metrics exposes process metrics for monitoring and should be restricted to trusted operators at the proxy/network layer.

Create an account and sign in

Registration sends an email verification code. Login validates the email and password, then sends a separate sign-in code. The API issues access and refresh tokens only after the sign-in code is verified.

curl -i http://localhost:8080/api/v1/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"mic","email":"mic@example.test","password":"replace-with-a-long-password","display_name":"Mic"}'

Complete email verification using the returned user ID and the code delivered to the account email:

curl -i http://localhost:8080/api/v1/auth/verify-email \
  -H 'Content-Type: application/json' \
  -d '{"user_id":"<user-id>","code":"<email-code>"}'

Request the sign-in code:

curl -i http://localhost:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"mic@example.test","password":"replace-with-a-long-password"}'

Verify it to receive the session:

curl -i http://localhost:8080/api/v1/auth/login/verify \
  -H 'Content-Type: application/json' \
  -d '{"email":"mic@example.test","code":"<sign-in-code>"}'

Use the access_token from the response as a bearer token:

curl http://localhost:8080/api/v1/auth/me \
  -H 'Authorization: Bearer <access-token>'

Keep tokens in a secure client store. Never put server secrets, MailAfrica keys, database credentials, or LiveKit API secrets in an Android build.

Request conventions

• All API resources live below /api/v1; health, readiness, and metrics are process-level routes.
• Send JSON with Content-Type: application/json for JSON bodies.
• Authenticated routes use Authorization: Bearer <access-token>.
• Send Idempotency-Key for order and payment creation so a network retry does not create a duplicate. Guest orders and all payment creation routes require it; member order creation accepts it as optional, but it is recommended for retries.
• Times use RFC3339 timestamps. Money uses integer minor units plus a three-letter currency.
• Paginated collection endpoints document their own query parameters; common order and admin collections use limit and offset.
• Responses use { "success": true, "data": ..., "meta": ..., "error": null, "request_id": "..." }. The current implementation does not return a top-level timestamp. Errors use the same envelope with success: false and a stable error.code.

Find the full contract

The endpoint reference lists every registered operation and its authentication, parameters, request fields, and response codes. The OpenAPI explorer renders the versioned OpenAPI contract. The downloadable source is openapi.yaml.

The OpenAPI paths were compared with the Go router: all 88 method/path pairs match the router as of 2026-10-12. Some operation request bodies are less complete in OpenAPI than in the handlers; the endpoint reference calls out the authoritative contract source and the API SRS describes the behavior.