> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnia-voice.com/llms.txt > Use this file to discover all available pages before exploring further. # Start a GRPO run > Start an online-RL run with a validated reward and hard budgets. Requires an owner/admin key. Refusals are explicit: unaligned or drift-flagged reward judges, a prompt population below the floor, missing platform-GPU configuration, or insufficient balance. The reward budget is enforced ledger-true: the reward server refuses scoring calls past it. ## OpenAPI ````yaml /openapi.json post /v1/grpo/runs openapi: 3.1.0 info: title: Omnia Management API description: >- The management API behind the improvement loop: capture and setup, request logs and datasets, grades (labels), judges (criteria), evals and deploy gates, fine-tuning and reinforcement learning, dedicated GPU endpoints, and model aliases and versions. Authenticated with a workspace API key (sk_sovereign_...). The inference API (chat, embeddings, rerank, responses) is OpenAI-compatible and documented separately. Responses are snake_case, list endpoints on the loop products use the {"object": "list", "data": [...]} envelope, and refusals use the same nested error shape the gateway emits: {"error": {"message", "type", "code"}}. Request bodies on the loop products (logs, labels, criteria, evals, datasets, aliases) are snake_case; the training and infrastructure products (fine-tuning, GRPO, environment tools, dedicated, model-version adoption) validate camelCase bodies, and each schema below says which it is. Endpoints that spend money require a key minted by a workspace owner or admin and return 403 otherwise. version: 1.0.0 servers: - url: https://gateway.omnia-voice.com description: Production - url: https://platform.omnia-voice.com/api description: Production (legacy alias — same API, older base URL) security: - bearerAuth: [] paths: /v1/grpo/runs: post: tags: - Reinforcement learning summary: Start a GRPO run description: >- Start an online-RL run with a validated reward and hard budgets. Requires an owner/admin key. Refusals are explicit: unaligned or drift-flagged reward judges, a prompt population below the floor, missing platform-GPU configuration, or insufficient balance. The reward budget is enforced ledger-true: the reward server refuses scoring calls past it. operationId: startGrpoRun requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateGrpoRun' responses: '201': description: Started. The run id appears in GET /v1/grpo/runs. content: application/json: schema: type: object properties: trigger_run_id: type: string description: Internal orchestration handle. '400': description: >- Invalid body (the error names the field), unvalidated reward, or an unusable configuration. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientBalance' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' components: schemas: CreateGrpoRun: type: object description: >- This body is camelCase (promptCount, rewardBudgetUsd), unlike the snake_case loop endpoints. Types and presence are validated at the route; numeric bounds live in the shared service, the same source of truth the dashboard uses. required: - reward - model - promptCount - rewardBudgetUsd - gpuHourBudget properties: reward: type: object description: >- The validated reward. Agentic runs (environment set) require a trace-unit aligned criterion. required: - mode properties: mode: type: string enum: - single - compositional criterionId: type: string description: >- mode single: the criterion whose judge scores rollouts. Unaligned or drift-flagged judges are refused: a reward you can't trust trains a model you can't trust. criterionIds: type: array description: >- mode compositional: the criteria whose judges combine into the reward. items: type: string assertions: type: array description: >- mode compositional: optional deterministic checks mixed into the reward. model: type: string description: The base model to train. promptTag: type: string description: Sample training prompts from traffic with this tag. promptCount: type: integer description: How many logged prompts feed the run. minimum: 1 groupSize: type: integer description: Completions sampled per prompt per step (the G in GRPO). maxSteps: type: integer rewardBudgetUsd: type: number description: >- Hard ceiling on judge/reward spend. The reward server refuses scoring calls past it (ledger-true kill switch). gpuHourBudget: type: number description: Wall-clock GPU budget, enforced by the orchestrator. useCandidateQueue: type: boolean description: >- Train on the workspace's GRPO-candidate queue (prompts offline RAFT gave up on) instead of a tag sample. platformGpu: type: object description: >- Platform-provisioned GPU: rate and markup are frozen at start and billed hourly while ACTIVE. Omit for a BYO-GPU run (no GPU billing). required: - gpuType - region properties: gpuType: type: string region: type: string gpuCount: type: integer allowSideEffects: type: boolean description: >- Agentic runs: permit calls to tools not declared read-only. Default false. default: false environment: type: object description: >- Agentic mode: run episodes against the declared tool environment (see /v1/env/tools). required: - proxy_base_url properties: proxy_base_url: type: string max_steps: type: integer simulate: type: boolean useVllm: type: boolean description: vLLM colocated rollouts. Forced on for agentic runs. vllmGpuMemoryUtilization: type: number qlora: type: boolean description: QLoRA 4-bit training. default: true paramsB: type: number description: Parameter-count override for models whose name doesn't carry it. autoProvision: type: boolean description: >- The platform provisions the GPU box (auto-sized). Refused when platform provisioning isn't configured. curriculumMixRatio: type: number description: >- Candidate-queue runs: fraction of the training slice drawn from regular successful traffic. minimum: 0 maximum: 0.9 holdoutCount: type: integer description: Holdout size for the bake-off; use 50+ for a real claim. maxCompletionTokens: type: integer description: >- Per-rollout generated-token budget. Agentic default 8192; single-turn 1024. tasksInline: type: array description: >- Task objects: {goal, image?, recorded?, verifier?: [{command, timeout_sec}]}. Max 10000. The unit of agentic work; benchmark suites import here. maxItems: 10000 autoAdopt: type: object description: >- Opt-in per run: an "improved" bake-off verdict triggers deploy, then a canary on this alias under the online gate. required: - aliasName - gpuType - region properties: aliasName: type: string maxLength: 120 canaryPercent: type: integer minimum: 1 maximum: 50 gpuType: type: string region: type: string templateFlavor: type: string Error: type: object properties: error: type: object properties: message: type: string type: type: string description: >- invalid_request_error, insufficient_quota, rate_limit_error, or api_error. code: type: string description: >- Machine-stable cause, e.g. invalid_api_key, not_found, insufficient_permissions, precondition_failed. required: - message - type - code description: >- Every refusal — gateway and management API alike — uses this one envelope. responses: Unauthorized: description: Missing, malformed, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: Invalid API key type: invalid_request_error code: invalid_api_key InsufficientBalance: description: Your wallet can't cover the required prepaid runway. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: message: >- Insufficient balance: deploying this endpoint requires at least 1h of runway. Top up and try again. type: insufficient_quota code: insufficient_balance Forbidden: description: The key lacks the required owner/admin permission. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Abuse guard tripped on a money-creating endpoint (default 20 requests per 60s per workspace). The body is a flat {"error", "type": "rate_limit_error"} object and the Retry-After header says when to retry. content: application/json: schema: type: object properties: error: type: string type: type: string securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your workspace API key, e.g. `sk_sovereign_...`, sent as `Authorization: Bearer `. ````