API Overview

Introduction to the Ryva REST API

Welcome to Ryva API

The Ryva API is a RESTful API that allows you to manage users, organizations, billing, and more. This documentation provides comprehensive information about all available endpoints, authentication methods, and data models.

Base URL

All API requests should be made to:

https://api.ryva.com

For local development:

http://localhost:8080

API Versioning

The Ryva API uses URL-based versioning. All endpoints are prefixed with /v1:

GET https://api.ryva.com/v1/auth/me

Current API version: v1

Response Format

All API responses are returned in JSON format with the following structure:

Success Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Example Org",
  "created_at": "2026-03-03T10:30:00Z"
}

Error Response

{
  "error": {
    "message": "Organization not found",
    "code": "NOT_FOUND",
    "status": 404
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

Status Code	Description
200	OK - Request successful
201	Created - Resource created successfully
204	No Content - Request successful, no response body
400	Bad Request - Invalid request parameters
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
409	Conflict - Resource already exists
422	Unprocessable Entity - Validation error
500	Internal Server Error - Server error

Common Error Codes

Code	Description
INVALID_REQUEST	The request body or parameters are invalid
UNAUTHORIZED	Authentication is required
FORBIDDEN	You don’t have permission to access this resource
NOT_FOUND	The requested resource was not found
CONFLICT	The resource already exists
VALIDATION_ERROR	Input validation failed
INTERNAL_ERROR	An internal server error occurred

Rate Limiting

API requests are rate limited to ensure fair usage:

• Authenticated requests: 1000 requests per hour
• Unauthenticated requests: 100 requests per hour

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1614556800

Timestamps

All timestamps are returned in ISO 8601 format with UTC timezone:

2026-03-03T10:30:00Z

Health Check

Check API availability:

curl https://api.ryva.com/health

Response:

{
  "status": "healthy"
}

Next Steps

Authentication

Learn how to authenticate your API requests

Auth Endpoints

Manage user profiles and preferences

Organizations

Create and manage organizations

Billing

Handle subscriptions and payments