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:

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

Rate limiting

Email sending is rate-limited:

Limit Value
Emails per hour 60
Emails per day 500
Attachment uploads per hour 200

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:

URL Description
/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