Requests and responses

The Sevah API uses HTTPS, JSON request bodies, and standard HTTP status codes. The API reference defines the exact contract for each operation.

Base URL and versioning

Send production requests to:

https://app.sevah.ai

Versioned application resources use the /api/v1/ prefix. Authentication and health endpoints have stable unversioned paths shown in the API reference.

Request headers

For JSON request bodies, send:

Content-Type: application/json
Accept: application/json

Include exactly one credential type required by the operation:

• Cookie: sevah_session=... for user-session operations.
• Authorization: Bearer ... for device-token operations.

Validate before changing state

For every response:

1. Check the HTTP status before decoding a success schema.
2. Validate required fields and types against the API reference.
3. Confirm resource identifiers and organization context match the request.
4. Treat unknown fields as forward-compatible additions unless your integration policy requires strict rejection.
5. Do not persist partial data after a failed validation.

The common error shape is:

{
  "error": "human-readable error"
}

Do not build application control flow by matching the error text. Use the HTTP status code and operation contract.

Status codes

Status	Meaning	Recommended handling
200 / 204	Request succeeded	Validate the documented success response.
400	Request is invalid	Correct the request; do not retry it unchanged.
401	Credential is missing, invalid, or expired	Reauthenticate once, then retry if safe.
403	Authenticated identity lacks access	Stop and request the required role or scope.
404	Resource is not visible or does not exist	Verify the identifier and organization context.
429	Request was rate limited	Retry with bounded exponential backoff and jitter.
503	A required service is temporarily unavailable	Retry a safe request with bounded backoff.

Safe retries

Automatically retry read-only requests after transient 429 or 503 responses. Use exponential backoff with jitter and a finite attempt limit.

Do not automatically replay a state-changing request unless the operation is documented as idempotent or your application can verify whether the first attempt succeeded. A network timeout does not prove that the server rejected the request.

Tenant boundaries

Protected resources are resolved within the organization attached to the user session. Treat a mismatched org_id, facility_id, room_id, patient_id, or device_id as a validation failure in your client, even if the response was otherwise successful.