API Overview

The Vidivo REST API is the backend interface for all platform operations. It follows standard REST conventions with JSON request and response bodies.

Base URL

https://api.vidivo.app/v1

All endpoints are relative to this base URL. The API is versioned — breaking changes will result in a new major version prefix (e.g. /v2).

Authentication

Most endpoints require authentication via a JWT Bearer token.

Authorization: Bearer <access_token>

Access tokens are short-lived (15 minutes). Use the refresh endpoint to obtain a new access token using your refresh token.

Tokens use RS256 signing (asymmetric RSA). Public keys are available at:

https://api.vidivo.app/.well-known/jwks.json

Token Types

Token	TTL	Usage
Access token	15 minutes	Bearer header on all authenticated requests
Refresh token	30 days	`POST /auth/refresh` only, rotated on use
Signaling token	5 minutes	WebSocket connection at `wss://signal.vidivo.app/ws`
Guest token	Session lifetime	Issued to unauthenticated guests before a call

Rate Limiting

Rate limits are enforced per IP address and per user.

Endpoint	Limit
`POST /auth/login`	5 requests per 15 minutes per IP
`POST /auth/register`	3 requests per hour per IP
All other endpoints	100 requests per minute per user
Unauthenticated endpoints	30 requests per minute per IP

When a rate limit is exceeded, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710000000

Error Format

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "invalid_credentials",
    "message": "The email or password is incorrect.",
    "details": null
  }
}

For validation errors, details contains field-level messages:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": {
      "email": "must be a valid email address",
      "password": "must be at least 8 characters"
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
`validation_error`	400	Request body failed validation
`unauthorized`	401	Missing or invalid auth token
`forbidden`	403	Valid token but insufficient permissions
`not_found`	404	Resource does not exist
`conflict`	409	Resource already exists (e.g. duplicate email)
`rate_limited`	429	Too many requests
`internal_error`	500	Unexpected server error
`stripe_error`	402	Stripe payment operation failed

Common Headers

Request Headers

Header	Required	Description
`Content-Type`	Yes (for POST/PUT)	Must be `application/json`
`Authorization`	Conditionally	`Bearer <access_token>` for authenticated endpoints
`X-Idempotency-Key`	Recommended	UUID v4 for payment mutations — prevents duplicate charges
`Accept-Language`	No	Preferred locale for error messages (default: `en`)

Response Headers

Header	Description
`X-Request-ID`	Unique request identifier for tracing. Include in bug reports.
`X-RateLimit-Limit`	Rate limit ceiling for the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets

Pagination

List endpoints that return multiple resources use cursor-based pagination:

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6IjEyMyJ9",
    "has_more": true,
    "limit": 20
  }
}

Pass the cursor in subsequent requests:

GET /calls?cursor=eyJpZCI6IjEyMyJ9&limit=20

WebSocket Signaling

WebRTC signaling uses a separate WebSocket endpoint:

wss://signal.vidivo.app/ws?token=<signaling_token>

Obtain a signaling_token from POST /calls/initiate. The token is valid for 5 minutes and is single-use per session. See the Calls API for details.

API Versioning

The current stable version is v1. When breaking changes are introduced, a new version will be published at /v2 with an appropriate migration guide. The old version will remain available for 6 months after a new version is released.

OpenAPI Specification

A machine-readable OpenAPI 3.1 specification is available at:

https://api.vidivo.app/v1/openapi.json