API Reference

The Asiri REST API exposes a public tenant API-key OpenAPI document for partner integrations and SDK generation. docs.asiri.ng documents the public surface only.

OpenAPI document

• Public JSON: https://api.asiri.ng/openapi-public.json
• Generated docs: API Reference

The public schema is the canonical reference for SDKs (@asiri-ng/sdk-ts, asiri-sdk) and external integrations.

The generated docs intentionally exclude first-party app routes, staff-only routes, session-only routes, and internal control-plane routes. Full internal schemas and Swagger UI are not exposed on the production API host.

Conventions

• Base URL: https://api.asiri.ng/v1 (production), https://api.staging.asiri.ng/v1 (staging).
• Versioning: path-based. Breaking changes ship under /v2. Non-breaking changes (additive fields, new endpoints) land in /v1.
• Auth: tenant API key bearer token in the Authorization header. First-party dashboard clients use session cookies against the full app schema. See Authentication.
• Content type: application/json requests and responses, UTF-8.
• Idempotency: mutating requests (POST, PUT, PATCH, DELETE) should include an Idempotency-Key header. Replays return the original response.
• Errors: JSON envelope shaped as { "error": { "code", "message", "details?", "requestId?" } }.
• Pagination: cursor-based. Responses include next_cursor; pass it as ?cursor=....
• Rate limits: per-key. X-RateLimit-Remaining and Retry-After headers tell you when to back off.

Stability

Public routes are versioned for partner integrations. Breaking changes ship under a new API version, while additive fields and new endpoints remain in the current version. The generated reference is regenerated from the live API schema whenever the API surface changes.