Rivya API v1 schema sources, compatibility rules, public fields और read-only OpenAPI JSON contract की समीक्षा करें.

Rivya API v1 read-only schema contract यहां expose करता है:

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

यह route public contract output है। यह user session data नहीं पढ़ता, model jobs submit नहीं करता, और private account data expose नहीं करता।

Contract Sources

Contract इन sources से derive होता है:

public API request schemas
public error codes
public API model reference layer
वही model catalog जिसे /api/v1/models इस्तेमाल करता है

Model list dynamic है। ऐसी integrations न बनाएं जो manually written model count पर निर्भर हों।

Version Policy

Current API version v1 है।

Backward-compatible changes में ये शामिल हो सकते हैं:

/api/v1/models में model जोड़ना
optional response field जोड़ना
किसी model के लिए optional request parameter जोड़ना
नया public error code जोड़ना

Breaking changes के लिए नई version या documented migration path चाहिए।

Public Field Boundary

Public schema fields public names इस्तेमाल करते हैं:

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

Internal task storage fields पर निर्भर न रहें। वे public contract का हिस्सा नहीं हैं।

Request Schema

POST /api/v1/generations स्वीकार करता है:

model: जरूरी public model ID
prompt: optional string, कई models में जरूरी
params: model-specific parameters वाला optional object
client_request_id: आपकी अपनी trace ID के लिए optional string

Model-specific params के लिए Model API Reference इस्तेमाल करें।

/api/v1/files से returned reference media params.referenceMediaItems के अंदर आता है। Schema url, kind, optional name, optional mimeType, optional durationSeconds और optional durationToken document करता है। Rivya top-level files field को POST /api/v1/generations में accept नहीं करता।

POST /api/v1/files multipart form data accept करता है जिसमें file, kind, optional model और optional client_request_id होते हैं। Response PublicApiFile है। GET /api/v1/files/{fileId} API account की owned files के लिए वही public file metadata return करता है।

POST /api/v1/chat/completions model, message, optional session_id, optional controls, optional Files API file_id attachments और optional client_request_id accept करता है। यह एक complete non-streaming assistant message return करता है।

POST /api/v1/chat/completions/stream वही request schema accept करता है और text/event-stream return करता है, जिसमें session.created, message.delta, message.completed, usage.completed, heartbeat, error और done events होते हैं। Chat API v1 raw messages array accept नहीं करता।

Response Schemas

OpenAPI output ये public response shapes document करता है:

ModelList for GET /api/v1/models
PublicApiModel और ModelParam for model selection and parameter forms
PublicApiFile for POST /api/v1/files और GET /api/v1/files/{fileId}
ReferenceMediaItem for file-backed generation parameters
PublicGeneration for create and status responses
GenerationResult और 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

Schema client validation और internal integration tests के लिए safe है। TypeScript SDK beta इसी schema से constrained रहता है।

Example Governance

इन docs में curl, JavaScript और Python examples वही public field names इस्तेमाल करते हैं जो schema में हैं:

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

Chat examples अतिरिक्त रूप से इस्तेमाल करते हैं:

chat:create
chat:read
file_id

Webhook examples अतिरिक्त रूप से इस्तेमाल करते हैं:

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

जब कोई model parameter बदलता है, तो पहले model catalog और public serializer update करें। Docs और debugger को अलग table copy करने के बजाय उसी public layer को consume करना चाहिए।

OpenAPI और Schema Contract