components:
    schemas:
        APIKeyCreateRequest:
            example:
                label: CI pipeline
                scopes:
                    - buyer:read
            properties:
                label:
                    type: string
                scopes:
                    items:
                        type: string
                    type: array
            type: object
        APIKeyCreateResponse:
            properties:
                api_key:
                    type: string
                key:
                    $ref: '#/components/schemas/APIKeyRecord'
            type: object
        APIKeyListResponse:
            properties:
                keys:
                    items:
                        $ref: '#/components/schemas/APIKeyRecord'
                    type: array
            type: object
        APIKeyRecord:
            example:
                buyer_id: buyer_9f2c7e1d
                created_at: "2026-03-08T13:30:00Z"
                hash_alg: hmac-sha256-v1
                key_id: jbswy3dp
                label: CI pipeline
                last_used_at: "2026-03-08T13:31:00Z"
                prefix: ryv_live_jbswy3dp
                revoked_at: null
                revoked_reason: ""
                scopes:
                    - buyer:read
            properties:
                buyer_id:
                    type: string
                created_at:
                    format: date-time
                    type: string
                hash_alg:
                    type: string
                key_id:
                    type: string
                label:
                    type: string
                last_used_at:
                    format: date-time
                    nullable: true
                    type: string
                prefix:
                    type: string
                revoked_at:
                    format: date-time
                    nullable: true
                    type: string
                revoked_reason:
                    type: string
                scopes:
                    items:
                        type: string
                    type: array
            type: object
        APIKeyRevokeRequest:
            example:
                reason: rotated
            properties:
                reason:
                    type: string
            type: object
        AuthRequest:
            example:
                email: operator@ryvion.ai
                name: Ryvion Buyer
                password: strong-password
            properties:
                email:
                    format: email
                    type: string
                name:
                    type: string
                password:
                    type: string
            required:
                - email
                - password
            type: object
        AuthResponse:
            example:
                api_key: ryv_live_jbswy3dp_3l6co4s6chf7mhg4sctoujtmnykq4e6
                buyer_id: buyer_9f2c7e1d
                email: operator@ryvion.ai
                name: Ryvion Buyer
                organization:
                    created_at: "2026-03-10T15:00:00Z"
                    id: org_buyer_9f2c7e1d
                    name: Ryvion Buyer
                    role: owner
                token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
            properties:
                api_key:
                    type: string
                buyer_id:
                    type: string
                email:
                    type: string
                name:
                    type: string
                organization:
                    $ref: '#/components/schemas/OrganizationContext'
                token:
                    type: string
            type: object
        CaptureSet:
            example:
                accuracy_profile: survey
                completed_at: "2026-03-11T12:18:00Z"
                created_at: "2026-03-11T12:15:00Z"
                id: cap_01JNY1G6Y4N0
                ingest_mode: manifest
                manifest_json: '{"capture_provider":"partner_a","assets":[{"path":"missions/epoch-12/0001.jpg","kind":"image/jpeg"}]}'
                manifest_version: v1
                raw_bytes: 524288000
                site_epoch_id: epoch_01JNY1BRC6A0
                source_partner_id: partner_a
                source_type: drone
                status: ready
                total_files: 240
                updated_at: "2026-03-11T12:18:00Z"
            properties:
                accuracy_profile:
                    type: string
                completed_at:
                    format: date-time
                    nullable: true
                    type: string
                created_at:
                    format: date-time
                    type: string
                id:
                    type: string
                ingest_mode:
                    type: string
                manifest_json:
                    type: string
                manifest_version:
                    type: string
                raw_bytes:
                    format: int64
                    type: integer
                site_epoch_id:
                    type: string
                source_partner_id:
                    type: string
                source_type:
                    type: string
                status:
                    enum:
                        - pending_upload
                        - uploading
                        - ready
                        - processing
                        - verified
                        - failed
                    type: string
                total_files:
                    type: integer
                updated_at:
                    format: date-time
                    type: string
            type: object
        CaptureSetCompleteRequest:
            example:
                raw_bytes: 524288000
                status: ready
                total_files: 240
            properties:
                manifest:
                    additionalProperties: true
                    type: object
                raw_bytes:
                    format: int64
                    type: integer
                status:
                    enum:
                        - pending_upload
                        - uploading
                        - ready
                        - processing
                        - verified
                        - failed
                    type: string
                total_files:
                    type: integer
            type: object
        CaptureSetCreateRequest:
            example:
                accuracy_profile: survey
                ingest_mode: manifest
                manifest:
                    assets:
                        - kind: image/jpeg
                          path: missions/epoch-12/0001.jpg
                    capture_provider: partner_a
                manifest_version: v1
                site_epoch_id: epoch_01JNY1BRC6A0
                source_partner_id: partner_a
                source_type: drone
                status: pending_upload
            properties:
                accuracy_profile:
                    type: string
                ingest_mode:
                    type: string
                manifest:
                    additionalProperties: true
                    type: object
                manifest_version:
                    type: string
                raw_bytes:
                    format: int64
                    type: integer
                site_epoch_id:
                    type: string
                source_partner_id:
                    type: string
                source_type:
                    type: string
                status:
                    enum:
                        - pending_upload
                        - uploading
                        - ready
                        - processing
                        - verified
                        - failed
                    type: string
                total_files:
                    type: integer
            required:
                - site_epoch_id
            type: object
        CaptureSetListResponse:
            properties:
                capture_sets:
                    items:
                        $ref: '#/components/schemas/CaptureSet'
                    type: array
                epoch:
                    $ref: '#/components/schemas/SiteEpoch'
                site:
                    $ref: '#/components/schemas/Site'
            type: object
        CaptureSetResponse:
            properties:
                capture_set:
                    $ref: '#/components/schemas/CaptureSet'
                epoch:
                    $ref: '#/components/schemas/SiteEpoch'
                site:
                    $ref: '#/components/schemas/Site'
            type: object
        ChatCompletionRequest:
            example:
                max_tokens: 256
                messages:
                    - content: How do I route work to Canada-only nodes?
                      role: user
                model: phi-4
                requires_tee: false
                stream: false
                strict_jurisdiction: CA
                temperature: 0.2
            properties:
                max_tokens:
                    type: integer
                messages:
                    items:
                        properties:
                            content:
                                type: string
                            role:
                                type: string
                        type: object
                    type: array
                model:
                    type: string
                requires_tee:
                    type: boolean
                stream:
                    type: boolean
                strict_jurisdiction:
                    type: string
                temperature:
                    type: number
            required:
                - model
                - messages
            type: object
        ChatCompletionResponse:
            additionalProperties: true
            example:
                choices:
                    - finish_reason: stop
                      index: 0
                      message:
                        content: Set the job region to a Canadian region and use a jurisdiction constraint if required.
                        role: assistant
                created: 1772751741
                id: chatcmpl_01HZZB4Q4X9R
                model: phi-4
                object: chat.completion
                usage:
                    completion_tokens: 19
                    prompt_tokens: 18
                    total_tokens: 37
            type: object
        ConfigResponse:
            additionalProperties: true
            example:
                default_runner_image: ghcr.io/ryvion/vllm-runner:latest
                dev_mode: false
                job_spec_version: 2026-02
            properties:
                default_runner_image:
                    type: string
                dev_mode:
                    type: boolean
                job_spec_version:
                    type: string
            type: object
        CreateWorkOrderRequest:
            properties:
                allowed_paths:
                    description: Repo path globs that the capsule may change without extra review.
                    items:
                        type: string
                    type: array
                architecture_plan:
                    type: string
                base_branch:
                    default: main
                    type: string
                forbidden_paths:
                    description: Repo path globs that block approval when changed.
                    items:
                        type: string
                    type: array
                goal:
                    type: string
                jurisdiction:
                    type: string
                policy_preset:
                    description: Architecture policy preset compiled into forbidden paths and required checks.
                    enum:
                        - custom
                        - review_only
                        - standard_feature
                        - frontend_ui
                        - backend_api
                        - sensitive_change
                        - infra_change
                    type: string
                repository_connection_id:
                    description: Saved repository connection to use for repo URL, default branch, and PR token reuse.
                    type: string
                repository_url:
                    type: string
                required_checks:
                    description: Command substrings that must appear in executed check commands before approval.
                    items:
                        type: string
                    type: array
                site_url:
                    type: string
                title:
                    type: string
                trust_tier:
                    default: certified
                    type: string
                work_branch:
                    type: string
            required:
                - goal
            type: object
        CreateWorkRepositoryRequest:
            properties:
                default_branch:
                    default: main
                    type: string
                github_token:
                    description: Optional GitHub token encrypted at rest for future PR creation.
                    type: string
                label:
                    type: string
                repository_url:
                    example: https://github.com/acme/product
                    type: string
            required:
                - repository_url
            type: object
        CreditTransaction:
            properties:
                amount_cents:
                    type: integer
                balance_after:
                    type: integer
                created_at:
                    format: date-time
                    type: string
                description:
                    type: string
                id:
                    type: string
                tx_type:
                    type: string
            type: object
        DownloadsInfoResponse:
            example:
                install_commands:
                    darwin: curl -fsSL https://api.ryvion.ai/install?platform=darwin | sh
                    linux: curl -fsSL https://api.ryvion.ai/install?platform=linux | sh
                    windows: powershell -ExecutionPolicy Bypass -File install.ps1
                platforms:
                    linux:
                        arch:
                            - amd64
                            - arm64
                    windows:
                        arch:
                            - amd64
                version: v1.2.17
            properties:
                install_commands:
                    additionalProperties:
                        type: string
                    type: object
                platforms:
                    additionalProperties: true
                    type: object
                version:
                    type: string
            type: object
        EmbeddingsRequest:
            example:
                input:
                    - Ryvion developer portal
                    - GPU marketplace
                model: nomic-embed-text
            properties:
                input:
                    items:
                        type: string
                    type: array
                model:
                    type: string
            required:
                - model
                - input
            type: object
        EmbeddingsResponse:
            additionalProperties: true
            example:
                data:
                    - embedding:
                        - 0.18
                        - 0.42
                        - 0.77
                        - 0.03
                      index: 0
                    - embedding:
                        - 0.11
                        - 0.54
                        - 0.63
                        - 0.08
                      index: 1
                model: nomic-embed-text
                object: list
            type: object
        ErrorResponse:
            properties:
                code:
                    type: integer
                error:
                    type: string
                message:
                    type: string
            type: object
        EstimateRequest:
            example:
                estimated_tokens: 3200
                kind: 1
            properties:
                estimated_data_gb:
                    type: integer
                estimated_duration_ms:
                    type: integer
                estimated_gpu_seconds:
                    type: integer
                estimated_images:
                    type: integer
                estimated_runs:
                    type: integer
                estimated_scenes:
                    type: integer
                estimated_tokens:
                    type: integer
                kind:
                    type: integer
            required:
                - kind
            type: object
        EstimateResponse:
            example:
                max_cost: 0.24
                max_cost_cents: 24
                min_cost: 0.12
                min_cost_cents: 12
                recommended_budget: 0.18
                recommended_cents: 18
            properties:
                max_cost:
                    type: number
                max_cost_cents:
                    type: integer
                min_cost:
                    type: number
                min_cost_cents:
                    type: integer
                recommended_budget:
                    type: number
                recommended_cents:
                    type: integer
            type: object
        EvidenceBundleResponse:
            additionalProperties: true
            properties:
                bundle_hash:
                    example: sha256:...
                    type: string
                evidence:
                    $ref: '#/components/schemas/EvidenceGraphResponse'
                generated_at:
                    format: date-time
                    type: string
                job:
                    additionalProperties: true
                    type: object
                policy_snapshot:
                    additionalProperties: true
                    type: object
                receipts:
                    items:
                        additionalProperties: true
                        type: object
                    type: array
                type:
                    example: ryvion.evidence_bundle.v1
                    type: string
                verifier:
                    additionalProperties: true
                    type: object
                work_order:
                    additionalProperties: true
                    description: Present on Work Order bundle endpoints; includes the Work Order snapshot, certification decision, approvals, PR, and rollback metadata.
                    type: object
            type: object
        EvidenceCertificate:
            properties:
                algorithm:
                    example: ed25519-sha256
                    type: string
                note:
                    type: string
                root_hash:
                    type: string
                signature_hex:
                    type: string
                signed:
                    type: boolean
                signed_at:
                    format: date-time
                    type: string
                signer_public_key_hex:
                    type: string
                verified:
                    description: True when the graph-root signature verifies against signer_public_key_hex.
                    type: boolean
                version:
                    example: RYV2-draft
                    type: string
            type: object
        EvidenceEdge:
            properties:
                edge_type:
                    example: then
                    type: string
                from_event_id:
                    type: string
                run_id:
                    type: string
                to_event_id:
                    type: string
            type: object
        EvidenceEvent:
            properties:
                created_at:
                    format: date-time
                    type: string
                event_hash:
                    example: sha256:4ac2...
                    type: string
                event_type:
                    example: receipt.verified
                    type: string
                id:
                    type: string
                metadata:
                    additionalProperties: true
                    type: object
                run_id:
                    type: string
                sequence:
                    type: integer
                subject_id:
                    type: string
                summary:
                    type: string
            type: object
        EvidenceGraphResponse:
            properties:
                certificate:
                    $ref: '#/components/schemas/EvidenceCertificate'
                edges:
                    items:
                        $ref: '#/components/schemas/EvidenceEdge'
                    type: array
                events:
                    items:
                        $ref: '#/components/schemas/EvidenceEvent'
                    type: array
                run:
                    $ref: '#/components/schemas/EvidenceRun'
            type: object
        EvidenceRun:
            properties:
                buyer_id:
                    type: string
                created_at:
                    format: date-time
                    type: string
                id:
                    type: string
                job_id:
                    type: string
                jurisdiction:
                    example: CA
                    type: string
                policy_id:
                    example: policy|jurisdiction:CA
                    type: string
                root_hash:
                    example: sha256:9bd1...
                    type: string
                root_signature_hex:
                    type: string
                signed_at:
                    format: date-time
                    type: string
                signer_public_key_hex:
                    type: string
                status:
                    example: completed
                    type: string
                summary:
                    type: string
                trust_tier:
                    example: sovereign
                    type: string
                updated_at:
                    format: date-time
                    type: string
                work_type:
                    example: rag
                    type: string
            type: object
        EvidenceRunsResponse:
            properties:
                limit:
                    type: integer
                offset:
                    type: integer
                runs:
                    items:
                        $ref: '#/components/schemas/EvidenceRun'
                    type: array
                total:
                    type: integer
            type: object
        HealthResponse:
            example:
                ok: true
                uptime: 14h23m18s
                version: 0.2.0
            properties:
                ok:
                    type: boolean
                uptime:
                    type: string
                version:
                    type: string
            type: object
        InferenceHealthResponse:
            properties:
                chat_models_in_catalog:
                    type: integer
                chat_models_with_capacity:
                    type: integer
                online_nodes_heartbeat_5m:
                    type: integer
                registered_nodes:
                    type: integer
            type: object
        MarketplaceAuditEvent:
            properties:
                at:
                    format: date-time
                    type: string
                details:
                    additionalProperties: true
                    type: object
                type:
                    type: string
            type: object
        MarketplaceAuditResponse:
            example:
                assigned_at: "2026-03-06T02:41:13Z"
                audit_generated: "2026-03-06T02:41:23Z"
                buyer_id: buyer_9f2c7e1d
                completed_at: "2026-03-06T02:41:22Z"
                created_at: "2026-03-06T02:41:10Z"
                credit_ledger:
                    - amount_cents: -18
                      balance_after: 2482
                      created_at: "2026-03-06T02:41:22Z"
                      description: Inference charge
                      id: txn_01HZZA7G4A6Q
                      tx_type: job_charge
                events:
                    - at: "2026-03-06T02:41:10Z"
                      details:
                        budget_cents: 500
                        region: ca-nl
                      type: job_submitted
                    - at: "2026-03-06T02:41:13Z"
                      details:
                        node_id: 0e5125f14e7e0d7dcb82c5f3a9...
                        region: St. John's, CA
                      type: job_assigned
                    - at: "2026-03-06T02:41:22Z"
                      details:
                        result_hash: 5fd4d6b0f31bf1f5a7a2f86f7b4b50...
                      type: job_completed
                job_id: job_01HZZA7DME2G
                receipts_count: 1
                status: completed
            properties:
                assigned_at:
                    format: date-time
                    type: string
                audit_generated:
                    format: date-time
                    type: string
                buyer_id:
                    type: string
                completed_at:
                    format: date-time
                    type: string
                created_at:
                    format: date-time
                    type: string
                credit_ledger:
                    items:
                        $ref: '#/components/schemas/CreditTransaction'
                    type: array
                events:
                    items:
                        $ref: '#/components/schemas/MarketplaceAuditEvent'
                    type: array
                job_id:
                    type: string
                receipts_count:
                    type: integer
                status:
                    type: string
            type: object
        MarketplaceJob:
            example:
                budget: 122
                budget_cents: 122
                compute_units: 600
                created_at: "2026-03-06T02:41:10Z"
                delivery_mode: dashboard
                delivery_target: Dashboard download
                estimated_cost: 1
                estimated_cost_cents: 1
                execution_pool: public
                id: job_01HZZA7DME2G
                job_type: transcoding
                max_price_per_unit: 1
                max_price_per_unit_cents: 1
                policy_note: Public pool workload. Country filters are enforced for placement, but this surface is not the sovereign training path.
                required_region: st. john's
                status: completed
                strict_jurisdiction: CA
                submitted_at: "2026-03-06T02:41:10Z"
            properties:
                budget:
                    type: integer
                budget_cents:
                    type: integer
                compute_units:
                    type: number
                created_at:
                    format: date-time
                    type: string
                delivery_artifact_put_url:
                    format: uri
                    type: string
                delivery_manifest_put_url:
                    format: uri
                    type: string
                delivery_mode:
                    type: string
                delivery_target:
                    type: string
                estimated_cost:
                    type: number
                estimated_cost_cents:
                    type: integer
                execution_pool:
                    description: Derived execution pool for the job. Public workloads use the public pool; confidential training and TEE-constrained work use the sovereign pool.
                    enum:
                        - public
                        - sovereign
                    type: string
                id:
                    type: string
                job_type:
                    type: string
                max_price_per_unit:
                    type: number
                max_price_per_unit_cents:
                    type: integer
                policy_note:
                    type: string
                required_region:
                    type: string
                status:
                    type: string
                strict_jurisdiction:
                    type: string
                submitted_at:
                    format: date-time
                    type: string
            type: object
        MarketplaceNodesResponse:
            example:
                nodes:
                    - availability: available
                      cpu_cores: 20
                      device_class: gpu
                      gpu_model: NVIDIA GeForce RTX 4070 Ti SUPER
                      gpu_ready: true
                      last_seen: 1772751427
                      managed_oci_gpu_ready: true
                      node_id: node_01HZZ8Y2B4G3
                      pubkey: 0e5125f14e7e0d7dcb82c5f3a9...
                      ram_gb: 64
                      region: St. John's, CA
                      status: online
                      vram_gb: 16
                    - availability: available
                      cpu_cores: 10
                      device_class: cpu
                      gpu_model: ""
                      gpu_ready: false
                      last_seen: 1772751420
                      managed_oci_gpu_ready: false
                      node_id: node_01HZZ8Y2B4G4
                      pubkey: 167520988d75ef7d6f8eb99d42...
                      ram_gb: 32
                      region: St. John's, CA
                      status: online
                      vram_gb: 0
                total: 2
            properties:
                nodes:
                    items:
                        $ref: '#/components/schemas/NodeSummary'
                    type: array
                total:
                    type: integer
            type: object
        MarketplacePostJobRequest:
            example:
                budget: 122
                currency: CAD
                estimated_duration_ms: 600000
                green_only: false
                kind: 3
                max_price_per_unit: 1
                min_reputation: 50
                payload_url: https://filesamples.com/samples/video/mp4/sample_640x360.mp4
                region: st. john's
                required_capabilities:
                    - cpu
                    - min_cpu_cores:8
                    - min_ram_gb:16
                strict_jurisdiction: CA
            properties:
                budget:
                    type: integer
                currency:
                    type: string
                delivery_artifact_put_url:
                    format: uri
                    type: string
                delivery_manifest_put_url:
                    format: uri
                    type: string
                delivery_mode:
                    type: string
                delivery_webhook_url:
                    format: uri
                    type: string
                estimated_data_gb:
                    type: integer
                estimated_duration_ms:
                    type: integer
                estimated_gpu_seconds:
                    type: integer
                estimated_images:
                    type: integer
                estimated_runs:
                    type: integer
                estimated_scenes:
                    type: integer
                estimated_tokens:
                    type: integer
                green_only:
                    type: boolean
                inline_text:
                    type: string
                kind:
                    type: integer
                max_price_per_unit:
                    type: number
                min_reputation:
                    type: integer
                output_file:
                    type: string
                payload_url:
                    format: uri
                    type: string
                region:
                    type: string
                required_capabilities:
                    items:
                        type: string
                    type: array
                requires_tee:
                    type: boolean
                runner_args:
                    items:
                        type: string
                    type: array
                strict_jurisdiction:
                    type: string
            required:
                - kind
                - budget
                - max_price_per_unit
                - currency
            type: object
        MarketplaceSLAResponse:
            example:
                assignment:
                    insufficient_sample: false
                    meets_target: true
                    p50_latency_ms: 2200
                    p95_latency_ms: 6100
                    samples: 14
                    target_p95_ms: 120000
                completion:
                    in_flight_jobs: 2
                    insufficient_sample: false
                    meets_target: true
                    success_rate: 1
                    target_success_rate: 0.95
                    terminal_jobs_considered: 12
                generated_at: "2026-03-06T03:00:00Z"
                totals:
                    assigned: 0
                    cancelled: 0
                    completed: 12
                    failed: 0
                    finished: 12
                    pending: 1
                    running: 1
                    submitted: 14
                window_hours: 24
                window_since: "2026-03-05T03:00:00Z"
            properties:
                assignment:
                    additionalProperties: true
                    type: object
                completion:
                    additionalProperties: true
                    type: object
                generated_at:
                    format: date-time
                    type: string
                totals:
                    additionalProperties:
                        type: integer
                    type: object
                window_hours:
                    type: integer
                window_since:
                    format: date-time
                    type: string
            type: object
        MeResponse:
            example:
                buyer_id: buyer_9f2c7e1d
                email: operator@ryvion.ai
                name: Ryvion Buyer
                organization:
                    created_at: "2026-03-10T15:00:00Z"
                    id: org_buyer_9f2c7e1d
                    name: Ryvion Buyer
                    role: owner
            properties:
                buyer_id:
                    type: string
                email:
                    type: string
                name:
                    type: string
                organization:
                    $ref: '#/components/schemas/OrganizationContext'
            type: object
        MessageResponse:
            properties:
                message:
                    type: string
            type: object
        NodeConnectCreateRequest:
            example:
                country: CA
                email: operator@ryvion.ai
            properties:
                country:
                    type: string
                email:
                    format: email
                    type: string
            required:
                - email
                - country
            type: object
        NodeConnectCreateResponse:
            example:
                account_id: acct_1RyvionExample
            properties:
                account_id:
                    type: string
            type: object
        NodeConnectOnboardingRequest:
            example:
                account_id: acct_1RyvionExample
            properties:
                account_id:
                    type: string
            required:
                - account_id
            type: object
        NodeConnectOnboardingResponse:
            example:
                url: https://connect.stripe.com/setup/s/acct_1RyvionExample
            properties:
                url:
                    format: uri
                    type: string
            type: object
        NodeConnectStatusResponse:
            example:
                account_id: acct_1RyvionExample
                onboarded: true
            properties:
                account_id:
                    type: string
                onboarded:
                    type: boolean
            type: object
        NodeReceiptRequest:
            example:
                green_multiplier_bps: 10000
                job_id: job_01HZZA7DME2G
                metadata:
                    duration_ms: 9012
                    model: phi-4
                metering_units: 3200
                pubkey: 0e5125f14e7e0d7dcb82c5f3a9...
                result_hash: 5fd4d6b0f31bf1f5a7a2f86f7b4b50...
                result_hash_hex: 5fd4d6b0f31bf1f5a7a2f86f7b4b50...
                signature: 0d2aa671...
            properties:
                green_multiplier_bps:
                    type: integer
                job_id:
                    type: string
                metadata:
                    additionalProperties: true
                    type: object
                metering_units:
                    type: integer
                pubkey:
                    type: string
                result_hash:
                    type: string
                result_hash_hex:
                    type: string
                signature:
                    type: string
            type: object
        NodeRegisterRequest:
            example:
                attestation_method: 1
                bandwidth_mbps: 950
                cpu_cores: 20
                device_type: gpu
                geohash_bucket: 0
                gpu_model: NVIDIA GeForce RTX 4070 Ti SUPER
                pubkey: 0e5125f14e7e0d7dcb82c5f3a9...
                ram_bytes: 68719476736
                sensors: '{"gpu_temp_c": 61, "gpu_power_w": 212}'
                signature: 5d6d0fa4e6cf...
                vram_bytes: 17179869184
            properties:
                attestation_method:
                    type: integer
                bandwidth_mbps:
                    type: integer
                cpu_cores:
                    type: integer
                device_type:
                    type: string
                geohash_bucket:
                    type: integer
                gpu_model:
                    type: string
                pubkey:
                    type: string
                ram_bytes:
                    type: integer
                sensors:
                    type: string
                signature:
                    type: string
                vram_bytes:
                    type: integer
            type: object
        NodeSummary:
            example:
                availability: available
                cpu_cores: 20
                device_class: gpu
                gpu_model: NVIDIA GeForce RTX 4070 Ti SUPER
                gpu_ready: true
                last_seen: 1772751427
                managed_oci_gpu_ready: true
                node_id: node_01HZZ8Y2B4G3
                pubkey: 0e5125f14e7e0d7dcb82c5f3a9...
                ram_gb: 64
                region: St. John's, CA
                status: online
                vram_gb: 16
            properties:
                availability:
                    type: string
                cpu_cores:
                    type: integer
                device_class:
                    type: string
                gpu_model:
                    type: string
                gpu_ready:
                    type: boolean
                last_seen:
                    type: integer
                managed_oci_gpu_ready:
                    type: boolean
                node_id:
                    type: string
                pubkey:
                    type: string
                ram_gb:
                    type: number
                region:
                    type: string
                status:
                    type: string
                vram_gb:
                    type: number
            type: object
        OpenAIModelsResponse:
            example:
                data:
                    - created: 1700000000
                      id: phi-4
                      object: model
                      owned_by: ryvion
                    - created: 1700000000
                      id: nomic-embed-text
                      object: model
                      owned_by: ryvion
                object: list
            properties:
                data:
                    items:
                        properties:
                            created:
                                type: integer
                            id:
                                type: string
                            object:
                                type: string
                            owned_by:
                                type: string
                        type: object
                    type: array
                object:
                    type: string
            type: object
        Organization:
            properties:
                created_at:
                    format: date-time
                    type: string
                id:
                    type: string
                name:
                    type: string
            type: object
        OrganizationAcceptInviteRequest:
            example:
                name: Ops Team
                password: strong-password
                token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
            properties:
                name:
                    type: string
                password:
                    type: string
                token:
                    type: string
            required:
                - token
                - password
            type: object
        OrganizationContext:
            properties:
                created_at:
                    format: date-time
                    type: string
                id:
                    type: string
                name:
                    type: string
                role:
                    enum:
                        - owner
                        - admin
                        - member
                    type: string
            type: object
        OrganizationInviteRequest:
            example:
                email: ops@customer.example
                role: member
            properties:
                email:
                    format: email
                    type: string
                role:
                    enum:
                        - admin
                        - member
                    type: string
            required:
                - email
            type: object
        OrganizationInviteResponse:
            properties:
                accept_url:
                    type: string
                email:
                    format: email
                    type: string
                expires_at:
                    format: date-time
                    type: string
                invite_token:
                    type: string
                organization:
                    $ref: '#/components/schemas/Organization'
                role:
                    enum:
                        - admin
                        - member
                    type: string
            type: object
        OrganizationMember:
            properties:
                buyer_id:
                    type: string
                created_at:
                    format: date-time
                    type: string
                email:
                    format: email
                    type: string
                name:
                    type: string
                role:
                    enum:
                        - owner
                        - admin
                        - member
                    type: string
            type: object
        OrganizationMembersResponse:
            properties:
                members:
                    items:
                        $ref: '#/components/schemas/OrganizationMember'
                    type: array
                organization:
                    $ref: '#/components/schemas/Organization'
            type: object
        OrganizationResponse:
            properties:
                member:
                    $ref: '#/components/schemas/OrganizationMember'
                organization:
                    $ref: '#/components/schemas/Organization'
            type: object
        PostJobResponse:
            example:
                estimated_cost: 0.18
                estimated_duration_ms: 9000
                job_id: job_01HZZA7DME2G
            properties:
                estimated_cost:
                    type: number
                estimated_duration_ms:
                    type: integer
                job_id:
                    type: string
            type: object
        PreflightWorkRepositoryRequest:
            properties:
                base_branch:
                    default: main
                    type: string
                jurisdiction:
                    description: Optional jurisdiction pin for the trusted preflight capsule.
                    type: string
                requires_tee:
                    type: boolean
                timeout_seconds:
                    default: 900
                    type: integer
                tooling:
                    example:
                        - git
                    items:
                        type: string
                    type: array
            type: object
        PreflightWorkRepositoryResponse:
            properties:
                base_branch:
                    type: string
                evidence_path:
                    type: string
                job_id:
                    type: string
                next_action:
                    type: string
                repository:
                    $ref: '#/components/schemas/WorkRepositoryConnection'
                status:
                    type: string
            type: object
        RollbackPoint:
            properties:
                base_branch:
                    type: string
                base_commit:
                    type: string
                created_at:
                    format: date-time
                    type: string
                deploy_ref:
                    type: string
                id:
                    type: string
                pr_url:
                    type: string
                work_branch:
                    type: string
                work_order_id:
                    type: string
            type: object
        RunWorkOrderRequest:
            properties:
                adapter:
                    enum:
                        - custom-command
                        - codex
                        - claude-code
                        - gemini-cli
                    type: string
                commands:
                    items:
                        type: string
                    type: array
                git_push:
                    description: Ask the trusted work capsule to commit and push the work branch. The node must provide Git credentials.
                    type: boolean
                requires_tee:
                    type: boolean
                test_commands:
                    items:
                        type: string
                    type: array
                timeout_seconds:
                    description: Clamped to the accepted work-capsule range.
                    type: integer
                tooling:
                    description: Tool capability requirements. Values are normalized and reject feature-injection characters.
                    items:
                        type: string
                    type: array
            type: object
        Site:
            example:
                aoi_geojson: '{"type":"Polygon","coordinates":[[[-73.6,45.5],[-73.5,45.5],[-73.5,45.6],[-73.6,45.6],[-73.6,45.5]]]}'
                baseline_bim_ref: s3://ryvion-baselines/site-001/model.ifc
                baseline_gis_ref: s3://ryvion-baselines/site-001/base.geojson
                country_code: CA
                created_at: "2026-03-11T12:00:00Z"
                crs: EPSG:4326
                external_ref: SITE-001
                id: site_01JNY0V2Y1K1
                name: Montreal logistics hub
                organization_id: org_buyer_9f2c7e1d
                region_code: QC
                site_type: industrial
                updated_at: "2026-03-11T12:00:00Z"
            properties:
                aoi_geojson:
                    type: string
                baseline_bim_ref:
                    type: string
                baseline_gis_ref:
                    type: string
                country_code:
                    type: string
                created_at:
                    format: date-time
                    type: string
                crs:
                    type: string
                external_ref:
                    type: string
                id:
                    type: string
                name:
                    type: string
                organization_id:
                    type: string
                region_code:
                    type: string
                site_type:
                    enum:
                        - construction
                        - utility
                        - campus
                        - corridor
                        - industrial
                        - insurance
                    type: string
                updated_at:
                    format: date-time
                    type: string
            type: object
        SiteCreateRequest:
            example:
                country_code: CA
                crs: EPSG:4326
                external_ref: SITE-001
                name: Montreal logistics hub
                region_code: QC
                site_type: industrial
            properties:
                aoi_geojson:
                    additionalProperties: true
                    type: object
                baseline_bim_ref:
                    type: string
                baseline_gis_ref:
                    type: string
                country_code:
                    type: string
                crs:
                    type: string
                external_ref:
                    type: string
                name:
                    type: string
                region_code:
                    type: string
                site_type:
                    enum:
                        - construction
                        - utility
                        - campus
                        - corridor
                        - industrial
                        - insurance
                    type: string
            required:
                - name
            type: object
        SiteEpoch:
            example:
                capture_window_end: "2026-03-10T17:00:00Z"
                capture_window_start: "2026-03-10T08:00:00Z"
                created_at: "2026-03-11T12:10:00Z"
                id: epoch_01JNY1BRC6A0
                label: 2026-03-11 weekly refresh
                site_id: site_01JNY0V2Y1K1
                source_mix: drone_rgb,lidar
                status: pending_ingest
                updated_at: "2026-03-11T12:10:00Z"
            properties:
                capture_window_end:
                    format: date-time
                    nullable: true
                    type: string
                capture_window_start:
                    format: date-time
                    nullable: true
                    type: string
                created_at:
                    format: date-time
                    type: string
                id:
                    type: string
                label:
                    type: string
                site_id:
                    type: string
                source_mix:
                    type: string
                status:
                    enum:
                        - draft
                        - pending_ingest
                        - processing
                        - ready
                        - completed
                        - failed
                    type: string
                updated_at:
                    format: date-time
                    type: string
            type: object
        SiteEpochCreateRequest:
            example:
                label: 2026-03-11 weekly refresh
                source_mix: drone_rgb,lidar
                status: pending_ingest
            properties:
                capture_window_end:
                    format: date-time
                    type: string
                capture_window_start:
                    format: date-time
                    type: string
                label:
                    type: string
                source_mix:
                    type: string
                status:
                    enum:
                        - draft
                        - pending_ingest
                        - processing
                        - ready
                        - completed
                        - failed
                    type: string
            type: object
        SiteEpochListResponse:
            properties:
                epochs:
                    items:
                        $ref: '#/components/schemas/SiteEpoch'
                    type: array
                site:
                    $ref: '#/components/schemas/Site'
            type: object
        SiteEpochResponse:
            properties:
                epoch:
                    $ref: '#/components/schemas/SiteEpoch'
                site:
                    $ref: '#/components/schemas/Site'
            type: object
        SiteListResponse:
            properties:
                organization:
                    $ref: '#/components/schemas/Organization'
                sites:
                    items:
                        $ref: '#/components/schemas/Site'
                    type: array
            type: object
        SiteResponse:
            properties:
                organization:
                    $ref: '#/components/schemas/Organization'
                site:
                    $ref: '#/components/schemas/Site'
            type: object
        StorageStatusResponse:
            example:
                bucket: ryvion-artifacts
                endpoint: https://s3.ca-central-1.amazonaws.com
                presign_available: true
                provider: s3
                region: ca-central-1
            properties:
                bucket:
                    type: string
                endpoint:
                    type: string
                presign_available:
                    type: boolean
                provider:
                    type: string
                region:
                    type: string
            type: object
        UsageLedgerResponse:
            properties:
                total_credits:
                    description: Sum of positive amount_cents rows in the returned window
                    type: integer
                total_debits:
                    description: Sum of absolute values of negative amount_cents rows in the returned window
                    type: integer
                transaction_count:
                    type: integer
                transactions:
                    items:
                        $ref: '#/components/schemas/CreditTransaction'
                    type: array
            type: object
        WorkApproval:
            properties:
                approver_id:
                    type: string
                comment:
                    type: string
                created_at:
                    format: date-time
                    type: string
                decision:
                    enum:
                        - approved
                        - rejected
                        - needs_changes
                    type: string
                evidence_root_hash:
                    type: string
                id:
                    type: string
                work_order_id:
                    type: string
            type: object
        WorkArtifact:
            properties:
                content_type:
                    type: string
                created_at:
                    format: date-time
                    type: string
                download_url:
                    description: Buyer-authenticated download route for this Work Order artifact.
                    type: string
                id:
                    type: string
                job_id:
                    type: string
                kind:
                    example: evidence_bundle
                    type: string
                label:
                    type: string
                metadata:
                    additionalProperties: true
                    type: object
                object_key:
                    type: string
                run_id:
                    type: string
                sha256:
                    type: string
                summary:
                    type: string
                url:
                    description: Original node-reported artifact URL when available. Prefer download_url for authenticated access.
                    type: string
                work_order_id:
                    type: string
            type: object
        WorkAssignmentResponse:
            example:
                has_work: true
                image: ghcr.io/ryvion/vllm-runner:latest
                job_id: job_01HZZA7DME2G
                job_pubkey: b53fd5a198f28c...
                kind: llm_inference
                payload_url: ""
                price_per_unit: 2
                spec_json: '{"model":"phi-4","messages":[{"role":"user","content":"Summarize this document"}]}'
                units: 3200
            properties:
                has_work:
                    type: boolean
                image:
                    type: string
                job_id:
                    type: string
                job_pubkey:
                    type: string
                kind:
                    type: string
                payload_url:
                    type: string
                price_per_unit:
                    type: integer
                spec_json:
                    type: string
                units:
                    type: integer
            type: object
        WorkOrder:
            properties:
                allowed_paths:
                    example:
                        - app/dashboard/**
                        - components/dashboard/**
                    items:
                        type: string
                    type: array
                approved_at:
                    format: date-time
                    type: string
                architecture_impact:
                    additionalProperties: true
                    type: object
                architecture_plan:
                    type: string
                assurance:
                    additionalProperties: true
                    properties:
                        level:
                            enum:
                                - L0
                                - L1
                                - L2
                                - L3
                                - L4
                                - L5
                                - L6
                            type: string
                        name:
                            type: string
                        not_claimed:
                            items:
                                type: string
                            type: array
                        proof_claim:
                            type: string
                    type: object
                base_branch:
                    example: main
                    type: string
                buyer_id:
                    type: string
                certification_decision:
                    additionalProperties: true
                    properties:
                        approve_allowed:
                            type: boolean
                        assurance_level:
                            enum:
                                - L0
                                - L1
                                - L2
                                - L3
                                - L4
                                - L5
                                - L6
                            type: string
                        assurance_name:
                            type: string
                        blockers:
                            items:
                                type: string
                            type: array
                        next_action:
                            type: string
                        not_claimed:
                            items:
                                type: string
                            type: array
                        pr_allowed:
                            type: boolean
                        proof_claim:
                            type: string
                        status:
                            enum:
                                - unknown
                                - awaiting_capsule
                                - running
                                - blocked
                                - ready_for_approval
                                - approved
                                - pr_created
                                - completed
                                - closed
                            type: string
                        warnings:
                            items:
                                type: string
                            type: array
                    type: object
                certification_level:
                    enum:
                        - pending_certificate
                        - verified_pr
                        - certified_work_capsule
                        - sovereign_certified_capsule
                        - confidential_capsule
                    type: string
                certification_summary:
                    type: string
                checks_status:
                    enum:
                        - not_run
                        - passed
                        - failed
                    type: string
                created_at:
                    format: date-time
                    type: string
                current_job_id:
                    type: string
                current_run_id:
                    type: string
                evidence_root_hash:
                    type: string
                evidence_run_id:
                    type: string
                forbidden_paths:
                    example:
                        - auth/**
                        - billing/**
                        - .env*
                    items:
                        type: string
                    type: array
                github_pr_url:
                    type: string
                goal:
                    type: string
                id:
                    example: wo_9bd1
                    type: string
                jurisdiction:
                    example: CA
                    type: string
                last_exit_code:
                    type: integer
                policy_preset:
                    enum:
                        - custom
                        - review_only
                        - standard_feature
                        - frontend_ui
                        - backend_api
                        - sensitive_change
                        - infra_change
                    type: string
                repository_connection_id:
                    type: string
                repository_url:
                    type: string
                required_checks:
                    example:
                        - npm run build
                        - npm run lint
                    items:
                        type: string
                    type: array
                risk_level:
                    enum:
                        - unknown
                        - low
                        - medium
                        - high
                        - review
                    type: string
                rollback_base_commit:
                    type: string
                site_url:
                    type: string
                status:
                    enum:
                        - draft
                        - planned
                        - running
                        - review_required
                        - approved
                        - pr_created
                        - completed
                        - failed
                        - cancelled
                        - rejected
                        - needs_changes
                    type: string
                title:
                    type: string
                trust_tier:
                    example: certified
                    type: string
                updated_at:
                    format: date-time
                    type: string
                work_branch:
                    example: ryvion/pricing-refresh
                    type: string
            type: object
        WorkOrderDecisionRequest:
            properties:
                comment:
                    type: string
                needs_changes:
                    type: boolean
            type: object
        WorkOrderDetailResponse:
            properties:
                approvals:
                    items:
                        $ref: '#/components/schemas/WorkApproval'
                    type: array
                artifacts:
                    items:
                        $ref: '#/components/schemas/WorkArtifact'
                    type: array
                rollback_points:
                    items:
                        $ref: '#/components/schemas/RollbackPoint'
                    type: array
                runs:
                    items:
                        $ref: '#/components/schemas/WorkOrderRun'
                    type: array
                work_order:
                    $ref: '#/components/schemas/WorkOrder'
            type: object
        WorkOrderPRRequest:
            properties:
                base:
                    type: string
                body:
                    type: string
                github_token:
                    description: Optional one-time token for creating the PR when the hub has no GitHub token configured.
                    type: string
                head:
                    type: string
                owner:
                    type: string
                pr_url:
                    type: string
                repo:
                    type: string
                title:
                    type: string
            type: object
        WorkOrderPreview:
            properties:
                allowed_paths:
                    items:
                        type: string
                    type: array
                architecture_plan:
                    type: string
                base_branch:
                    example: main
                    type: string
                certification_decision:
                    additionalProperties: true
                    type: object
                forbidden_paths:
                    items:
                        type: string
                    type: array
                likely_touched_areas:
                    items:
                        type: string
                    type: array
                policy_preset:
                    enum:
                        - custom
                        - review_only
                        - standard_feature
                        - frontend_ui
                        - backend_api
                        - sensitive_change
                        - infra_change
                    type: string
                preflight_recommended:
                    type: boolean
                profile_available:
                    type: boolean
                repo_profile:
                    additionalProperties: true
                    description: Last trusted repository profile used to compile the plan, if available.
                    type: object
                repository_connection_id:
                    type: string
                repository_url:
                    type: string
                required_checks:
                    items:
                        type: string
                    type: array
                risk_level:
                    enum:
                        - low
                        - medium
                        - high
                        - review
                    type: string
                risk_reasons:
                    items:
                        type: string
                    type: array
            type: object
        WorkOrderPreviewResponse:
            properties:
                preview:
                    $ref: '#/components/schemas/WorkOrderPreview'
            type: object
        WorkOrderRun:
            properties:
                adapter:
                    example: codex
                    type: string
                completed_at:
                    format: date-time
                    type: string
                evidence_root:
                    type: string
                evidence_run_id:
                    type: string
                executor_kind:
                    example: work_capsule
                    type: string
                failure_message:
                    type: string
                id:
                    type: string
                job_id:
                    type: string
                metadata:
                    additionalProperties: true
                    type: object
                node_public_key:
                    type: string
                started_at:
                    format: date-time
                    type: string
                status:
                    type: string
                work_order_id:
                    type: string
            type: object
        WorkOrdersResponse:
            properties:
                limit:
                    type: integer
                offset:
                    type: integer
                total:
                    type: integer
                work_orders:
                    items:
                        $ref: '#/components/schemas/WorkOrder'
                    type: array
            type: object
        WorkRepositoriesResponse:
            properties:
                limit:
                    type: integer
                offset:
                    type: integer
                repositories:
                    items:
                        $ref: '#/components/schemas/WorkRepositoryConnection'
                    type: array
                total:
                    type: integer
            type: object
        WorkRepositoryConnection:
            properties:
                buyer_id:
                    type: string
                created_at:
                    format: date-time
                    type: string
                default_branch:
                    example: main
                    type: string
                has_token:
                    type: boolean
                id:
                    type: string
                label:
                    type: string
                owner:
                    type: string
                provider:
                    enum:
                        - github
                    type: string
                repo:
                    type: string
                repo_profile:
                    additionalProperties: true
                    description: Last trusted capsule repository profile, if available.
                    type: object
                repository_url:
                    type: string
                token_prefix:
                    description: Masked token prefix/suffix only. The token is never returned.
                    type: string
                updated_at:
                    format: date-time
                    type: string
            type: object
        WorkloadCatalogEntry:
            properties:
                available_nodes:
                    type: integer
                certification_basis:
                    type: string
                certified_nodes:
                    type: integer
                description:
                    type: string
                estimate_defaults:
                    additionalProperties: true
                    type: object
                execution_pool:
                    enum:
                        - public
                        - sovereign
                    type: string
                green_only:
                    type: boolean
                id:
                    type: string
                kind:
                    type: string
                kind_id:
                    type: integer
                max_cost:
                    type: number
                max_cost_cents:
                    type: integer
                min_cost:
                    type: number
                min_cost_cents:
                    type: integer
                min_reputation:
                    type: integer
                name:
                    type: string
                policy_note:
                    type: string
                publicly_orderable:
                    type: boolean
                recommended_budget:
                    type: number
                recommended_cents:
                    type: integer
                recommended_region:
                    type: string
                required_capabilities:
                    items:
                        type: string
                    type: array
                requires_gpu:
                    type: boolean
                runnable_now:
                    type: boolean
                sample_label:
                    type: string
                sample_units:
                    type: number
                unit:
                    type: string
                unit_price_cents:
                    type: integer
                value_tag:
                    type: string
                vertical:
                    type: string
            type: object
        WorkloadCatalogResponse:
            example:
                currency: CAD
                generated_at: "2026-03-06T03:00:00Z"
                online_nodes:
                    cpu: 1
                    gpu: 3
                    total: 4
                workloads:
                    - available_nodes: 1
                      certification_basis: verified transcode receipts
                      certified_nodes: 1
                      description: Large queues for VOD adaptation, clipping, and archive conversion.
                      estimate_defaults:
                        estimated_duration_ms: 600000
                      execution_pool: public
                      green_only: false
                      id: video_transcode_queue
                      kind: transcoding
                      kind_id: 3
                      max_cost: 1.65
                      max_cost_cents: 165
                      min_cost: 1.05
                      min_cost_cents: 105
                      min_reputation: 50
                      name: Video Transcode Queue
                      policy_note: Public pool workload. strict_jurisdiction remains an auditable country filter, but this order flow is not the confidential-training surface.
                      publicly_orderable: true
                      recommended_budget: 1.22
                      recommended_cents: 122
                      recommended_region: ca-central
                      required_capabilities:
                        - cpu
                        - min_cpu_cores:8
                        - min_ram_gb:16
                      requires_gpu: false
                      runnable_now: true
                      sample_label: 10 minutes
                      sample_units: 600
                      unit: second
                      unit_price_cents: 1
                      value_tag: Throughput Scale
                      vertical: Media Pipeline
                    - available_nodes: 1
                      certification_basis: native report capability and signed receipts
                      certified_nodes: 0
                      description: Native node-agent processing for site notes and photo manifests.
                      estimate_defaults:
                        estimated_duration_ms: 120000
                        estimated_runs: 1
                      execution_pool: public
                      green_only: false
                      id: inspection_report_processing
                      kind: data_processing
                      kind_id: 4
                      max_cost: 3
                      max_cost_cents: 300
                      min_cost: 1.25
                      min_cost_cents: 125
                      min_reputation: 50
                      name: Verified Inspection Report
                      policy_note: Public pool workload. Runs through the native report executor without requiring managed OCI.
                      publicly_orderable: true
                      recommended_budget: 2.5
                      recommended_cents: 250
                      recommended_region: ca-central
                      required_capabilities:
                        - native-report
                        - cpu
                        - min_cpu_cores:2
                        - min_disk_gb:2
                      requires_gpu: false
                      runnable_now: true
                      sample_label: 1 report
                      sample_units: 1
                      unit: run
                      unit_price_cents: 250
                      value_tag: Auditable Report
                      vertical: AEC + Inspection
            properties:
                currency:
                    type: string
                generated_at:
                    format: date-time
                    type: string
                online_nodes:
                    additionalProperties:
                        type: integer
                    type: object
                workloads:
                    items:
                        $ref: '#/components/schemas/WorkloadCatalogEntry'
                    type: array
            type: object
    securitySchemes:
        BuyerApiKey:
            in: header
            name: X-API-Key
            type: apiKey
        BuyerBearer:
            bearerFormat: JWT
            scheme: bearer
            type: http
        NodeToken:
            in: header
            name: X-Node-Token
            type: apiKey
info:
    description: Public buyer, operator, and OpenAI-compatible API for the Ryvion compute marketplace.
    title: Ryvion Hub API
    version: 0.3.0
openapi: 3.0.3
paths:
    /api/v1/analytics:
        get:
            description: Returns aggregated usage statistics for the authenticated buyer. Results are cached for 5 minutes.
            parameters:
                - in: query
                  name: period
                  schema:
                    default: 7d
                    enum:
                        - 24h
                        - 7d
                        - 30d
                        - 90d
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    daily:
                                        items:
                                            properties:
                                                cost_cents:
                                                    format: int64
                                                    type: integer
                                                date:
                                                    format: date
                                                    type: string
                                                errors:
                                                    type: integer
                                                input_tokens:
                                                    format: int64
                                                    type: integer
                                                output_tokens:
                                                    format: int64
                                                    type: integer
                                                requests:
                                                    type: integer
                                            type: object
                                        type: array
                                    error_rate:
                                        format: float
                                        type: number
                                    period:
                                        type: string
                                    top_models:
                                        items:
                                            properties:
                                                model:
                                                    type: string
                                                requests:
                                                    type: integer
                                                tokens:
                                                    format: int64
                                                    type: integer
                                            type: object
                                        type: array
                                    total_cost_cents:
                                        format: int64
                                        type: integer
                                    total_requests:
                                        type: integer
                                    total_tokens:
                                        format: int64
                                        type: integer
                                type: object
                    description: Analytics result
                    headers:
                        X-Analytics-Cache:
                            description: '"hit" when served from cache'
                            schema:
                                type: string
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Buyer usage analytics
            tags:
                - Analytics
    /api/v1/auth/api-keys:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/APIKeyListResponse'
                    description: Current API keys for the buyer
            security:
                - BuyerBearer: []
            summary: List buyer API keys
            tags:
                - Auth
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/APIKeyCreateRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/APIKeyCreateResponse'
                    description: New API key created. The plaintext key is returned only once.
            security:
                - BuyerBearer: []
            summary: Create buyer API key
            tags:
                - Auth
    /api/v1/auth/api-keys/{key}/revoke:
        post:
            parameters:
                - in: path
                  name: key
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/APIKeyRevokeRequest'
                required: false
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    key_id:
                                        type: string
                                    revoked:
                                        type: boolean
                                type: object
                    description: API key revoked
            security:
                - BuyerBearer: []
            summary: Revoke buyer API key
            tags:
                - Auth
    /api/v1/auth/login:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AuthRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AuthResponse'
                    description: Buyer authenticated
            summary: Login buyer
            tags:
                - Auth
    /api/v1/auth/me:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MeResponse'
                    description: Buyer profile
            security:
                - BuyerBearer: []
            summary: Current buyer identity
            tags:
                - Auth
    /api/v1/auth/org:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/OrganizationResponse'
                    description: Organization and current membership
            security:
                - BuyerBearer: []
            summary: Current buyer organization
            tags:
                - Auth
    /api/v1/auth/org/accept-invite:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/OrganizationAcceptInviteRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AuthResponse'
                    description: Invite accepted and buyer authenticated
            summary: Accept an organization invite
            tags:
                - Auth
    /api/v1/auth/org/invites:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/OrganizationInviteRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/OrganizationInviteResponse'
                    description: Invite created
            security:
                - BuyerBearer: []
            summary: Create an organization invite
            tags:
                - Auth
    /api/v1/auth/org/members:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/OrganizationMembersResponse'
                    description: Organization members
            security:
                - BuyerBearer: []
            summary: List current organization members
            tags:
                - Auth
    /api/v1/auth/request-reset:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                email:
                                    format: email
                                    type: string
                            required:
                                - email
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MessageResponse'
                    description: Reset request accepted
            summary: Request password reset
            tags:
                - Auth
    /api/v1/auth/reset-password:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                new_password:
                                    type: string
                                token:
                                    type: string
                            required:
                                - token
                                - new_password
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MessageResponse'
                    description: Password updated
            summary: Reset password with a short-lived token
            tags:
                - Auth
    /api/v1/auth/signup:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AuthRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AuthResponse'
                    description: Buyer created and authenticated
            summary: Create buyer account
            tags:
                - Auth
    /api/v1/billing/balance:
        get:
            description: Returns the authenticated buyer's current credit balance and Stripe metadata.
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    balance_cents:
                                        description: Current balance in cents (CAD)
                                        type: integer
                                    currency:
                                        example: CAD
                                        type: string
                                    stripe_customer_id:
                                        type: string
                                type: object
                    description: Balance response
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Get credit balance
            tags:
                - Billing
    /api/v1/billing/credits:
        post:
            description: Charges the buyer's saved Stripe payment method and adds credits.
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                amount_cents:
                                    description: Amount to purchase in cents (CAD). Minimum 100 (= $1).
                                    example: 5000
                                    type: integer
                            required:
                                - amount_cents
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    new_balance_cents:
                                        type: integer
                                    status:
                                        example: ok
                                        type: string
                                type: object
                    description: Purchase result
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Purchase credits
            tags:
                - Billing
    /api/v1/billing/transactions:
        get:
            description: Returns the transaction ledger for the authenticated buyer.
            parameters:
                - in: query
                  name: limit
                  schema:
                    default: 50
                    type: integer
                - in: query
                  name: offset
                  schema:
                    default: 0
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    transactions:
                                        items:
                                            properties:
                                                amount_cents:
                                                    type: integer
                                                balance_after:
                                                    type: integer
                                                created_at:
                                                    format: date-time
                                                    type: string
                                                description:
                                                    type: string
                                                id:
                                                    type: string
                                                tx_type:
                                                    type: string
                                            type: object
                                        type: array
                                type: object
                    description: Transactions list
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List billing transactions
            tags:
                - Billing
    /api/v1/config:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ConfigResponse'
                    description: Runtime configuration
            summary: Public hub configuration
            tags:
                - Health
    /api/v1/downloads/info:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DownloadsInfoResponse'
                    description: Download commands and versions
            summary: Installer and binary metadata
            tags:
                - Nodes
    /api/v1/epochs/{epoch}/capture-sets:
        get:
            parameters:
                - in: path
                  name: epoch
                  required: true
                  schema:
                    type: string
                - in: query
                  name: limit
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CaptureSetListResponse'
                    description: Capture sets for the epoch
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List capture sets for an epoch
            tags:
                - Reality
    /api/v1/evidence:
        get:
            parameters:
                - in: query
                  name: limit
                  schema:
                    default: 50
                    maximum: 200
                    type: integer
                - in: query
                  name: offset
                  schema:
                    default: 0
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EvidenceRunsResponse'
                    description: Evidence runs for the authenticated buyer
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List buyer evidence runs
            tags:
                - Evidence
    /api/v1/evidence/{id}:
        get:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EvidenceGraphResponse'
                    description: Hash-linked evidence graph
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Get one evidence graph
            tags:
                - Evidence
    /api/v1/evidence/{id}/bundle:
        get:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EvidenceBundleResponse'
                    description: Downloadable evidence bundle with RYV1 receipts, RYV2 graph, policy snapshot, and verifier metadata
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Export one evidence bundle
            tags:
                - Evidence
    /api/v1/health/inference:
        get:
            description: |
                Registered nodes, nodes with heartbeat under 5 minutes, and how many chat models have at least one capable online node.
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InferenceHealthResponse'
                    description: Public capacity snapshot
            summary: Inference capacity snapshot
            tags:
                - Health
    /api/v1/ingest/capture-sets:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CaptureSetCreateRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CaptureSetResponse'
                    description: Capture set created
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Create a capture set
            tags:
                - Reality
    /api/v1/ingest/capture-sets/{captureSet}/complete:
        post:
            parameters:
                - in: path
                  name: captureSet
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CaptureSetCompleteRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CaptureSetResponse'
                    description: Capture set updated
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Mark a capture set complete or ready
            tags:
                - Reality
    /api/v1/jobs/{job}/evidence:
        get:
            parameters:
                - in: path
                  name: job
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EvidenceGraphResponse'
                    description: Hash-linked evidence graph for the job
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Get evidence graph for a buyer job
            tags:
                - Evidence
    /api/v1/jobs/{job}/evidence/bundle:
        get:
            parameters:
                - in: path
                  name: job
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EvidenceBundleResponse'
                    description: Downloadable evidence bundle for the job
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Export evidence bundle for a buyer job
            tags:
                - Evidence
    /api/v1/knowledge-bases:
        get:
            description: Lists all knowledge bases owned by the authenticated buyer.
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    knowledge_bases:
                                        items:
                                            properties:
                                                created_at:
                                                    format: date-time
                                                    type: string
                                                document_count:
                                                    type: integer
                                                id:
                                                    type: string
                                                jurisdiction:
                                                    type: string
                                                name:
                                                    type: string
                                            type: object
                                        type: array
                                type: object
                    description: Knowledge bases list
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List knowledge bases
            tags:
                - Knowledge Bases
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                jurisdiction:
                                    description: Restrict embedding/retrieval to nodes in this jurisdiction.
                                    example: CA
                                    type: string
                                name:
                                    example: Product documentation
                                    type: string
                            required:
                                - name
                            type: object
                required: true
            responses:
                "201":
                    description: Created knowledge base
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Create knowledge base
            tags:
                - Knowledge Bases
    /api/v1/knowledge-bases/{id}/documents:
        post:
            description: Uploads and indexes a document into the knowledge base.
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            properties:
                                file:
                                    format: binary
                                    type: string
                            type: object
                required: true
            responses:
                "201":
                    description: Document queued for processing
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Upload document
            tags:
                - Knowledge Bases
    /api/v1/knowledge-bases/{id}/search:
        post:
            description: Performs vector similarity search over documents in a knowledge base.
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                query:
                                    example: How do I route jobs to Canadian nodes?
                                    type: string
                                top_k:
                                    default: 5
                                    description: Number of results to return.
                                    type: integer
                            required:
                                - query
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    results:
                                        items:
                                            properties:
                                                chunk_id:
                                                    type: string
                                                chunk_index:
                                                    type: integer
                                                content:
                                                    type: string
                                                hall_type:
                                                    type: string
                                                relevance:
                                                    format: float
                                                    type: number
                                            type: object
                                        type: array
                                type: object
                    description: Search results
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Semantic search
            tags:
                - Knowledge Bases
    /api/v1/marketplace/estimate:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/EstimateRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EstimateResponse'
                    description: Cost estimate
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Estimate marketplace job cost
            tags:
                - Marketplace
    /api/v1/marketplace/jobs:
        get:
            parameters:
                - in: query
                  name: limit
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            example:
                                - budget: 500
                                  budget_cents: 500
                                  compute_units: 3200
                                  created_at: "2026-03-06T02:41:10Z"
                                  estimated_cost: 0.18
                                  estimated_cost_cents: 18
                                  id: job_01HZZA7DME2G
                                  job_type: llm_inference
                                  max_price_per_unit: 0.02
                                  max_price_per_unit_cents: 2
                                  required_region: ca-nl
                                  status: completed
                                  submitted_at: "2026-03-06T02:41:10Z"
                            schema:
                                items:
                                    $ref: '#/components/schemas/MarketplaceJob'
                                type: array
                    description: Recent marketplace jobs
            summary: List public marketplace jobs
            tags:
                - Marketplace
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/MarketplacePostJobRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PostJobResponse'
                    description: Job accepted
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Submit a marketplace job
            tags:
                - Marketplace
    /api/v1/marketplace/jobs/{job}/audit:
        get:
            parameters:
                - in: path
                  name: job
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MarketplaceAuditResponse'
                    description: Job audit response
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Get buyer job audit trail
            tags:
                - Marketplace
    /api/v1/marketplace/jobs/{job}/audit/export:
        get:
            parameters:
                - in: path
                  name: job
                  required: true
                  schema:
                    type: string
                - in: query
                  name: format
                  schema:
                    enum:
                        - json
                        - csv
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                type: string
                        text/csv:
                            schema:
                                format: binary
                                type: string
                    description: Audit export file
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Export buyer job audit
            tags:
                - Marketplace
    /api/v1/marketplace/jobs/{job}/dispute:
        post:
            description: Submits a dispute for a failed or cancelled job. If the job can be auto-refunded, credits are returned immediately.
            parameters:
                - in: path
                  name: job
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                reason:
                                    example: Job produced incorrect output
                                    type: string
                            required:
                                - reason
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    message:
                                        type: string
                                    refunded_cents:
                                        type: integer
                                    status:
                                        enum:
                                            - auto_refunded
                                            - filed
                                        type: string
                                type: object
                    description: Dispute filed or auto-refunded
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Dispute a failed job
            tags:
                - Marketplace
    /api/v1/marketplace/models:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            example:
                                available_models:
                                    - available_nodes: 3
                                      id: phi-4
                                      image: streaming
                                      requires_gpu: true
                                      type: streaming
                                    - available_nodes: 4
                                      id: nomic-embed-text
                                      image: ghcr.io/ryvion/embed-runner:0.1.0
                                      requires_gpu: false
                                      type: container
                                total_nodes: 4
                            schema:
                                additionalProperties: true
                                type: object
                    description: Model catalog and availability
            summary: List marketplace models
            tags:
                - Marketplace
    /api/v1/marketplace/my/jobs:
        get:
            parameters:
                - in: query
                  name: limit
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            example:
                                - budget: 500
                                  budget_cents: 500
                                  compute_units: 3200
                                  created_at: "2026-03-06T02:41:10Z"
                                  estimated_cost: 0.18
                                  estimated_cost_cents: 18
                                  id: job_01HZZA7DME2G
                                  job_type: llm_inference
                                  max_price_per_unit: 0.02
                                  max_price_per_unit_cents: 2
                                  required_region: ca-nl
                                  status: completed
                                  submitted_at: "2026-03-06T02:41:10Z"
                            schema:
                                items:
                                    $ref: '#/components/schemas/MarketplaceJob'
                                type: array
                    description: Jobs owned by the authenticated buyer
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List buyer marketplace jobs
            tags:
                - Marketplace
    /api/v1/marketplace/nodes:
        get:
            parameters:
                - in: query
                  name: limit
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MarketplaceNodesResponse'
                    description: Node list
            summary: List marketplace nodes
            tags:
                - Marketplace
    /api/v1/marketplace/sla:
        get:
            parameters:
                - in: query
                  name: window_hours
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MarketplaceSLAResponse'
                    description: Completion and assignment metrics
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Get buyer SLA window
            tags:
                - Marketplace
    /api/v1/marketplace/workloads:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkloadCatalogResponse'
                    description: Workload catalog
            summary: List workload catalog entries
            tags:
                - Marketplace
    /api/v1/node/connect/create:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/NodeConnectCreateRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NodeConnectCreateResponse'
                    description: Connect account created
            security:
                - NodeToken: []
            summary: Create node payout account
            tags:
                - Nodes
    /api/v1/node/connect/onboarding-link:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/NodeConnectOnboardingRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NodeConnectOnboardingResponse'
                    description: Onboarding link generated
            security:
                - NodeToken: []
            summary: Create node payout onboarding link
            tags:
                - Nodes
    /api/v1/node/connect/status:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/NodeConnectStatusResponse'
                    description: Current onboarding state
            security:
                - NodeToken: []
            summary: Get node payout onboarding status
            tags:
                - Nodes
    /api/v1/node/health:
        post:
            responses:
                "200":
                    description: Health report accepted
            summary: Submit node health report
            tags:
                - Nodes
    /api/v1/node/heartbeat:
        post:
            responses:
                "200":
                    description: Heartbeat accepted
            summary: Submit node heartbeat
            tags:
                - Nodes
    /api/v1/node/payout/save:
        post:
            responses:
                "200":
                    description: Wallet saved
            summary: Save node payout wallet
            tags:
                - Nodes
    /api/v1/node/receipt:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/NodeReceiptRequest'
                required: true
            responses:
                "200":
                    description: Receipt accepted
            summary: Submit node receipt
            tags:
                - Nodes
    /api/v1/node/register:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/NodeRegisterRequest'
                required: true
            responses:
                "200":
                    description: Registration accepted
            summary: Register node
            tags:
                - Nodes
    /api/v1/node/work:
        get:
            parameters:
                - in: query
                  name: pubkey
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkAssignmentResponse'
                    description: Work assignment response
            summary: Get node work assignment
            tags:
                - Nodes
    /api/v1/sites:
        get:
            parameters:
                - in: query
                  name: limit
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SiteListResponse'
                    description: Site list
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List sites for the current organization
            tags:
                - Reality
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/SiteCreateRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SiteResponse'
                    description: Site created
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Create a site
            tags:
                - Reality
    /api/v1/sites/{site}:
        get:
            parameters:
                - in: path
                  name: site
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SiteResponse'
                    description: Site details
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Get a site
            tags:
                - Reality
    /api/v1/sites/{site}/epochs:
        get:
            parameters:
                - in: path
                  name: site
                  required: true
                  schema:
                    type: string
                - in: query
                  name: limit
                  schema:
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SiteEpochListResponse'
                    description: Site epochs
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List epochs for a site
            tags:
                - Reality
        post:
            parameters:
                - in: path
                  name: site
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/SiteEpochCreateRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SiteEpochResponse'
                    description: Site epoch created
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Create an epoch for a site
            tags:
                - Reality
    /api/v1/storage/status:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/StorageStatusResponse'
                    description: Storage provider information
            summary: Blob storage status
            tags:
                - Health
    /api/v1/usage:
        get:
            description: |
                Returns recent credit transactions with debit/credit totals. Optional `start` and `end` query parameters filter by `created_at` (RFC3339); `end` is exclusive.
            parameters:
                - description: Inclusive lower bound on transaction `created_at`
                  in: query
                  name: start
                  required: false
                  schema:
                    format: date-time
                    type: string
                - description: Exclusive upper bound on transaction `created_at`
                  in: query
                  name: end
                  required: false
                  schema:
                    format: date-time
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UsageLedgerResponse'
                    description: Ledger rows and aggregates
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Missing or invalid buyer authentication
            security:
                - BuyerBearer: []
                - BuyerApiKey: []
            summary: Buyer credit ledger sample
            tags:
                - Health
    /api/v1/work-orders:
        get:
            parameters:
                - in: query
                  name: limit
                  schema:
                    default: 50
                    maximum: 200
                    type: integer
                - in: query
                  name: offset
                  schema:
                    default: 0
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkOrdersResponse'
                    description: Work orders for the authenticated buyer
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List buyer work orders
            tags:
                - Work Orders
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateWorkOrderRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkOrderDetailResponse'
                    description: Work order created
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Create certified AI work order
            tags:
                - Work Orders
    /api/v1/work-orders/{id}:
        get:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkOrderDetailResponse'
                    description: Work order, runs, artifacts, approvals, and rollback points
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Get work order detail
            tags:
                - Work Orders
    /api/v1/work-orders/{id}/approve:
        post:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WorkOrderDecisionRequest'
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkOrderDetailResponse'
                    description: Approval recorded
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Approve a reviewed work order
            tags:
                - Work Orders
    /api/v1/work-orders/{id}/artifacts:
        get:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    artifacts:
                                        items:
                                            $ref: '#/components/schemas/WorkArtifact'
                                        type: array
                                type: object
                    description: Work artifacts
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List artifacts for a work order
            tags:
                - Work Orders
    /api/v1/work-orders/{id}/artifacts/{artifact}/download:
        get:
            description: Streams local artifacts or redirects to a short-lived signed object URL when the backing blob store supports presigned downloads.
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
                - in: path
                  name: artifact
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/octet-stream:
                            schema:
                                format: binary
                                type: string
                    description: Artifact content
                "307":
                    description: Redirect to signed artifact URL
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Download a Work Order artifact through buyer-authenticated access
            tags:
                - Work Orders
    /api/v1/work-orders/{id}/evidence:
        get:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EvidenceGraphResponse'
                    description: Hash-linked evidence graph for the work order
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Get evidence graph for a work order
            tags:
                - Work Orders
    /api/v1/work-orders/{id}/evidence/bundle:
        get:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EvidenceBundleResponse'
                    description: Downloadable evidence bundle for the work order
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Export evidence bundle for a work order
            tags:
                - Work Orders
    /api/v1/work-orders/{id}/github/pr:
        post:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WorkOrderPRRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkOrderDetailResponse'
                    description: Pull request attached to the work order
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Create or attach GitHub pull request for approved work
            tags:
                - Work Orders
    /api/v1/work-orders/{id}/reject:
        post:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WorkOrderDecisionRequest'
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkOrderDetailResponse'
                    description: Decision recorded
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Reject or request changes for a work order
            tags:
                - Work Orders
    /api/v1/work-orders/{id}/run:
        post:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/RunWorkOrderRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkOrderDetailResponse'
                    description: Work capsule job queued
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Queue trusted work capsule run
            tags:
                - Work Orders
    /api/v1/work-orders/preview:
        post:
            description: Compiles policy presets, saved repository profiles, likely touched areas, required checks, and approval blockers before creating a Work Order.
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateWorkOrderRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkOrderPreviewResponse'
                    description: Work Order plan preview
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Preview architecture-aware BuildOps plan
            tags:
                - Work Orders
    /api/v1/work-repositories:
        get:
            parameters:
                - in: query
                  name: limit
                  schema:
                    default: 50
                    maximum: 200
                    type: integer
                - in: query
                  name: offset
                  schema:
                    default: 0
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkRepositoriesResponse'
                    description: Saved repository connections
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: List saved repository connections
            tags:
                - Work Orders
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateWorkRepositoryRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                properties:
                                    repository:
                                        $ref: '#/components/schemas/WorkRepositoryConnection'
                                type: object
                    description: Repository connection saved
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Save a repository connection for BuildOps work orders
            tags:
                - Work Orders
    /api/v1/work-repositories/{id}:
        delete:
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            responses:
                "204":
                    description: Repository connection deleted
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Delete a saved repository connection
            tags:
                - Work Orders
    /api/v1/work-repositories/{id}/preflight:
        post:
            description: Runs a profile-only work capsule on a trusted node to capture repository architecture, suggested checks, and sensitive path rules before AI execution.
            parameters:
                - in: path
                  name: id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PreflightWorkRepositoryRequest'
            responses:
                "202":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PreflightWorkRepositoryResponse'
                    description: Repository preflight job queued
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Queue trusted repository preflight profiling
            tags:
                - Work Orders
    /healthz:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/HealthResponse'
                    description: Liveness response
            summary: Hub liveness probe
            tags:
                - Health
    /v1/chat/completions:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ChatCompletionRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ChatCompletionResponse'
                        text/event-stream:
                            schema:
                                type: string
                    description: Chat completion response
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Create chat completion
            tags:
                - Gateway
    /v1/embeddings:
        post:
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/EmbeddingsRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/EmbeddingsResponse'
                    description: Embeddings response
            security:
                - BuyerApiKey: []
                - BuyerBearer: []
            summary: Create embeddings
            tags:
                - Gateway
    /v1/models:
        get:
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/OpenAIModelsResponse'
                    description: Available models
            summary: List gateway models
            tags:
                - Gateway
servers:
    - description: Current hub
      url: https://ryvion-hub.fly.dev
tags:
    - description: Service health and public runtime metadata.
      name: Health
    - description: Downloadable API schema documents.
      name: Docs
    - description: Buyer account and session endpoints.
      name: Auth
    - description: Site, epoch, and capture-set workflows for operational digital twins.
      name: Reality
    - description: Buyer marketplace endpoints for models, jobs, audit, and SLA data.
      name: Marketplace
    - description: Operator node registration, polling, receipts, and payout onboarding.
      name: Nodes
    - description: OpenAI-compatible chat and embedding endpoints.
      name: Gateway
    - description: Credit balance, transactions, and payment methods.
      name: Billing
    - description: Usage analytics for the authenticated buyer.
      name: Analytics
    - description: RYV2 draft evidence graphs for receipt-backed AI work items.
      name: Evidence
    - description: BuildOps work orders for controlled AI-executed software delivery.
      name: Work Orders
    - description: RAG document stores, semantic search, and agent memory.
      name: Knowledge Bases
    - description: Custom model fine-tuning jobs and checkpoints.
      name: Fine-tuning
    - description: Hosted agent deployment management.
      name: Agents
