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 /v1/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

User Roles

Access to endpoints is governed by the user’s role. Roles follow a progression:

Role	Description
guest	Unauthenticated caller with a guest session token
user	Registered user with unverified email
verified_user	Email verified, not yet a host
host	Age-verified user who can create call links and receive payouts
admin	Platform administrator with full access

Rate Limiting

Rate limits are enforced per IP address and per user.

Endpoint	Limit
POST /v1/auth/login	5 requests per 15 minutes per IP
POST /v1/auth/register	3 requests per hour per IP
POST /v1/auth/password/reset	10 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

Success Response Format

Successful responses wrap data in a standard envelope:

{
  "success": true,
  "data": { ... }
}

Paginated responses include pagination metadata:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}

Pagination Parameters

List endpoints use page-based pagination:

Query Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
per_page	integer	20	Results per page (max 100)

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-API-Version	API version string
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

API Endpoints Summary

Authentication (/v1/auth/)

Method	Path	Auth	Description
POST	/auth/register	No	Create account
POST	/auth/login	No	Login
POST	/auth/refresh	No	Refresh tokens
POST	/auth/logout	No	Logout
POST	/auth/verify-email	No	Verify email
POST	/auth/password/reset	No	Request password reset
POST	/auth/password/confirm	No	Confirm password reset
POST	/auth/google	No	Google OAuth login
POST	/auth/apple	No	Apple Sign-In
POST	/auth/guest-session	No	Create guest session

Users (/v1/users/)

Method	Path	Auth	Description
GET	/users/me	Yes	Get own profile
PUT	/users/me	Yes	Update profile
PUT	/users/me/avatar	Yes	Upload avatar
POST	/users/me/become-host	Yes	Become a host
PUT	/users/me/rate	Yes	Set billing rate
PUT	/users/me/toggle-available	Yes	Toggle availability
GET	/users/me/availability	Yes	Get schedule
PUT	/users/me/availability	Yes	Set schedule
GET	/users/:username	No	Public host profile

Calls (/v1/calls/)

Method	Path	Auth	Description
POST	/calls/join/:short_code	Guest/User	Join via link
POST	/calls/:id/host-join	Host	Host joins call
POST	/calls/:id/end	Yes	End call
GET	/calls/:id	Yes	Get call details
GET	/calls/history	Yes	Call history
POST	/calls/links	Host	Create call link
GET	/calls/links	Host	List call links
DELETE	/calls/links/:id	Host	Delete call link
GET	/calls/links/:shortCode/info	No	Link public info

Payments (/v1/payments/)

Method	Path	Auth	Description
GET	/payments/history	Yes	Payment history
GET	/payments/history/export	Yes	Export payments
GET	/payments/earnings	Host	Earnings summary
GET	/payments/earnings/chart	Host	Earnings chart
POST	/payments/payout	Host	Request payout
GET	/payments/payouts	Host	Payout history

Chat (/v1/chat/)

Method	Path	Auth	Description
GET	/chat/conversations	Yes	List conversations
POST	/chat/conversations	Yes	Create conversation
GET	/chat/conversations/:id/messages	Yes	Get messages
POST	/chat/conversations/:id/messages	Yes	Send message
POST	/chat/broadcast	Host	Broadcast to followers

See individual API reference pages for full request/response details.

WebSocket Endpoints

URL	Description
wss://signal.vidivo.app/signal/ws	WebRTC signaling
wss://api.vidivo.app/v1/chat/ws?token=JWT	Real-time chat

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.

Note

The Vidivo API is currently in active development. Endpoints documented here reflect the latest build. Some features may be refined before the public launch.