Rivya AI Docs

OpenAPI and Schema Contract

Review Rivya API v1 schema sources, compatibility rules, public fields, and the read-only OpenAPI JSON contract.

Last reviewed on 2026/05/11

Rivya API v1 exposes a read-only schema contract at:

https://rivya.ai/api/v1/openapi.json

This route is a public contract output. It does not read user session data, does not submit model jobs, and does not expose private account data.

Contract Sources

The contract is derived from:

  • public API request schemas
  • public error codes
  • the public API model reference layer
  • the same model catalog used by /api/v1/models

The model list is dynamic. Do not build integrations that depend on a manually written model count.

Version Policy

The current API version is v1.

Backward-compatible changes may include:

  • adding a model to /api/v1/models
  • adding an optional response field
  • adding an optional request parameter for a model
  • adding a new public error code

Breaking changes require a new version or a documented migration path.

Public Field Boundary

Public schema fields use public names:

  • id
  • status
  • model
  • session_id
  • message
  • usage
  • reserved_credits
  • final_credits
  • created_at
  • updated_at
  • result
  • error

Do not depend on internal task storage fields. They are not part of the public contract.

Request Schema

POST /api/v1/generations accepts:

  • model: required public model ID
  • prompt: optional string, required by many models
  • params: optional object with model-specific parameters
  • client_request_id: optional string for your own trace ID

Use Model API Reference for model-specific params.

Reference media returned by /api/v1/files belongs inside params.referenceMediaItems. The schema documents url, kind, optional name, optional mimeType, optional durationSeconds, and optional durationToken. Rivya does not accept a top-level files field in POST /api/v1/generations.

POST /api/v1/files accepts multipart form data with file, kind, optional model, and optional client_request_id. The response is PublicApiFile. GET /api/v1/files/{fileId} returns the same public file metadata for files owned by the API account.

POST /api/v1/chat/completions accepts model, message, optional session_id, optional controls, optional Files API file_id attachments, and optional client_request_id. It returns one complete non-streaming assistant message.

POST /api/v1/chat/completions/stream accepts the same request schema and returns text/event-stream with session.created, message.delta, message.completed, usage.completed, heartbeat, error, and done events. Chat API v1 does not accept a raw messages array.

Response Schemas

The OpenAPI output documents these public response shapes:

  • ModelList for GET /api/v1/models
  • PublicApiModel and ModelParam for model selection and parameter forms
  • PublicApiFile for POST /api/v1/files and GET /api/v1/files/{fileId}
  • ReferenceMediaItem for file-backed generation parameters
  • PublicGeneration for create and status responses
  • GenerationResult and GenerationError for completed tasks
  • ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits, and Chat stream event schemas for Chat API
  • CreditBalance for GET /api/v1/credits
  • WebhookEndpoint, WebhookEvent, WebhookDelivery, and WebhookTestResult for signed API webhooks
  • PublicApiError for stable error responses

The schema is safe to use for client validation and internal integration tests. The TypeScript SDK beta stays constrained by this schema.

Example Governance

curl, JavaScript, and Python examples in these docs use the same public field names as the schema:

  • Authorization: Bearer rvya_sk_...
  • Idempotency-Key
  • model
  • prompt
  • message
  • session_id
  • params
  • client_request_id

Chat examples additionally use:

  • chat:create
  • chat:read
  • file_id

Webhook examples additionally use:

  • Rivya-Webhook-Signature
  • Rivya-Webhook-Timestamp
  • webhooks:manage

When a model parameter changes, update the model catalog and public serializer first. The docs and debugger should consume that same public layer instead of copying a separate table.

API Models

List Rivya API models, understand model IDs, categories, prompt limits, reference media, readiness states, and Files API dependencies.

Rivya API Quickstart

Create an API key, choose a model, submit an asynchronous generation job, and send a Chat API turn with optional SSE streaming.

Table of Contents

Contract Sources
Version Policy
Public Field Boundary
Request Schema
Response Schemas
Example Governance
Related Pages