Ravi

API Overview

Base URL

https://ravi.app

All API endpoints are prefixed with /api/.

Authentication

All API requests require a Bearer JWT token in the Authorization header:

Authorization: Bearer <access-token>

Tokens are obtained via the device-code flow. The CLI and plugins handle this automatically.

Identity scoping

Most endpoints require an Identity scope. Pass the Identity UUID in the X-Ravi-Identity header:

X-Ravi-Identity: <identity-uuid>

Without this header, endpoints that require Identity scoping will return an error.

Response format

All responses are JSON. The API uses standard HTTP status codes:

StatusMeaning
200Success
201Created
204Deleted (no content)
400Bad request (validation error)
401Unauthorized (invalid or expired token)
402Payment required (subscription needed)
404Not found
429Rate limited (retry after delay)

Rate limiting

Email sending is rate-limited:

LimitValue
Emails per hour60
Emails per day500
Attachment uploads per hour200

Rate limit responses include a retry_after_seconds field.

E2E encryption

Encrypted fields use the format "e2e::<base64>". The API accepts and returns this ciphertext — encryption and decryption happen client-side. Fields that may be encrypted:

  • Password entries: password, username, notes
  • Vault secrets: value, notes
  • Email content at rest

The encryption metadata endpoint (/api/encryption/) provides the salt and public key needed for key derivation.

Server-Sent Events

Real-time updates are delivered via SSE at /api/events/stream/. Events include:

  • email — new incoming email
  • sms — new incoming SMS

SSE events are plaintext (the server decrypts before pushing). The stream supports Last-Event-ID for reconnection.

API documentation (development)

When running the backend locally with DEBUG=True:

URLDescription
/api/docs/Swagger UI — interactive API explorer
/api/redoc/ReDoc — read-only reference docs
/api/schema/Raw OpenAPI YAML schema

These are not available in production.

Next steps