OpenAPI Specification
Document Info
- Purpose
- Describes the machine-readable OpenAPI 3.1 contract for the ELVA Notify backend API.
- Intended Audience
- Integrators, client developers, and maintainers who need a formal API contract.
- Last Updated
- 2026-06-05
- Related Documents
- API Reference IntroAuthenticationOTP APINotify APIError Codes
Overview
The OpenAPI specification is the source of truth for the HTTP API contract. It lives in the backend package:
text
backend/openapi/
├── openapi.yaml
└── components/
├── schemas.yaml
├── errors.yaml
└── security.yamlThe documentation portal consumes a generated manifest at build/dev time:
text
backend/openapi/openapi.yaml
↓
frontend/scripts/generate-openapi-manifest.mjs
↓
frontend/.generated/openapi-manifest.json
↓
/api-reference pages + searchCovered operations
| Method | Path | Auth |
|---|---|---|
GET | /health | No |
POST | /otp/send | Yes (appId, apiKey in body) |
POST | /otp/resend | Yes |
POST | /otp/verify | Yes |
POST | /notify | Yes |
GET / (static HTML landing page) is not included in the OpenAPI spec.
Authentication model
Credentials are sent in the JSON request body, not headers. The spec documents appId and apiKey on protected request schemas and uses x-elva-auth metadata on operations.
See Authentication for the narrative guide.
Validation
From the repository root:
bash
npm run openapi:validateThis validates the spec and component references. It is development tooling only — no runtime impact.
Interactive reference
Browse the searchable endpoint catalog:
For narrative flows and examples, continue using OTP and Notify.