openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "RenderTrust API",
    "description": "A general-purpose trust fabric for any computational service",
    "version": "0.1.0"
  },
  "paths": {
    "/api/v1/health": {
      "get": {
        "tags": [
          "health"
        ],
        "summary": "Health Check",
        "description": "Liveness probe. Returns healthy if the process is running.",
        "operationId": "health_check_api_v1_health_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object",
                  "title": "Response Health Check Api V1 Health Get"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health/ready": {
      "get": {
        "tags": [
          "health"
        ],
        "summary": "Readiness Check",
        "description": "Readiness probe. Checks database and Redis connectivity.\n\nReturns 200 with component status if all services are reachable.\nReturns 200 with degraded status if any service is unreachable\n(allows the application to start even if dependencies are slow).",
        "operationId": "readiness_check_api_v1_health_ready_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object",
                  "title": "Response Readiness Check Api V1 Health Ready Get"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/register": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Register",
        "description": "Create a new user account and return JWT tokens.\n\nRaises:\n    HTTPException 409: If the email is already registered.",
        "operationId": "register_api_v1_auth_register_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Login",
        "description": "Authenticate with email and password, returning JWT tokens.\n\nRaises:\n    HTTPException 401: Invalid credentials or inactive account.",
        "operationId": "login_api_v1_auth_login_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/refresh": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Refresh",
        "description": "Exchange a valid refresh token for a new access + refresh token pair.\n\nRaises:\n    HTTPException 401: Invalid, expired, or wrong-type token.",
        "operationId": "refresh_api_v1_auth_refresh_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/logout": {
      "post": {
        "tags": [
          "auth"
        ],
        "summary": "Logout",
        "description": "Revoke the current access token.\n\nDecodes the Bearer token and adds its JTI to a Redis blacklist\nwith a TTL matching the token's remaining lifetime.  Subsequent\ncalls to ``verify_token`` will reject the blacklisted token.\n\nReturns:\n    Confirmation message (always succeeds from the caller's perspective).",
        "operationId": "logout_api_v1_auth_logout_post",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/api/v1/webhooks/stripe": {
      "post": {
        "tags": [
          "billing"
        ],
        "summary": "Stripe Hook",
        "description": "Handle incoming Stripe webhook events.\n\nVerifies the webhook signature using the endpoint secret,\nthen dispatches the event based on its type. All events are\nacknowledged with ``{\"received\": True}`` to prevent Stripe\nretries for successfully received (but possibly unhandled)\nevent types.\n\nCredit allocation for ``checkout.session.completed`` events is\nidempotent -- Stripe retries are safe because the ledger service\nuses the checkout session ID as a deduplication key.\n\nReturns:\n    dict: ``{\"received\": True}`` on successful processing.\n\nRaises:\n    HTTPException(400): If the signature header is missing,\n        the signature is invalid, or the payload cannot be parsed.",
        "operationId": "stripe_hook_api_v1_webhooks_stripe_post",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object",
                  "title": "Response Stripe Hook Api V1 Webhooks Stripe Post"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/credits/balance": {
      "get": {
        "tags": [
          "credits"
        ],
        "summary": "Credit Balance",
        "description": "Return the current credit balance for the authenticated user.",
        "operationId": "credit_balance_api_v1_credits_balance_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BalanceResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/api/v1/credits/history": {
      "get": {
        "tags": [
          "credits"
        ],
        "summary": "Credit History",
        "description": "Return paginated credit transaction history for the authenticated user.",
        "operationId": "credit_history_api_v1_credits_history_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 100,
              "minimum": 1,
              "default": 50,
              "title": "Limit"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "title": "Offset"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HistoryResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/credits/deduct": {
      "post": {
        "tags": [
          "credits"
        ],
        "summary": "Credit Deduct",
        "description": "Deduct credits from the authenticated user's account.\n\nReturns 402 if the user has insufficient credits.\nReturns 422 if the amount is not a valid positive decimal.",
        "operationId": "credit_deduct_api_v1_credits_deduct_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeductRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerEntryResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/api/v1/nodes/register": {
      "post": {
        "tags": [
          "scheduler",
          "scheduler"
        ],
        "summary": "Register",
        "description": "Register a new edge node with Ed25519 public key.\n\nReturns a challenge string that must be signed by the node's private key\nto complete identity verification, along with a node JWT for subsequent\nauthenticated requests (heartbeat, job dispatch).",
        "operationId": "register_api_v1_nodes_register_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NodeRegisterRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NodeRegisterResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/nodes/heartbeat": {
      "post": {
        "tags": [
          "scheduler",
          "scheduler"
        ],
        "summary": "Heartbeat",
        "description": "Process heartbeat from authenticated edge node.\n\nRequires a valid node JWT in the Authorization header.\nUpdates last_heartbeat timestamp, current_load, and transitions\nREGISTERED/UNHEALTHY nodes to HEALTHY.",
        "operationId": "heartbeat_api_v1_nodes_heartbeat_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HeartbeatRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HeartbeatResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/api/v1/jobs/dispatch": {
      "post": {
        "tags": [
          "dispatch",
          "dispatch"
        ],
        "summary": "Dispatch",
        "description": "Dispatch a job to the least-loaded healthy edge node.\n\nRequires a valid user JWT in the Authorization header.\nThe scheduler selects the least-loaded HEALTHY node that has\nthe required ``job_type`` in its capabilities list.\n\nReturns 201 with the job dispatch confirmation, or 503 if no\nsuitable node is available.",
        "operationId": "dispatch_api_v1_jobs_dispatch_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DispatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DispatchResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        },
        "security": [
          {
            "HTTPBearer": []
          }
        ]
      }
    },
    "/api/v1/jobs": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "List Jobs Endpoint",
        "description": "List jobs with optional status filter and pagination.\n\nAll jobs are returned (no per-user filtering -- JobDispatch has no\nuser_id column yet). Authentication is still required.",
        "operationId": "list_jobs_endpoint_api_v1_jobs_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Status"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "maximum": 100,
              "minimum": 1,
              "default": 50,
              "title": "Limit"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0,
              "title": "Offset"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobListResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "Get Job Endpoint",
        "description": "Get a single job by ID.\n\nReturns 404 if the job does not exist, 422 if the ID format is invalid.",
        "operationId": "get_job_endpoint_api_v1_jobs__job_id__get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}/cancel": {
      "post": {
        "tags": [
          "jobs"
        ],
        "summary": "Cancel Job Endpoint",
        "description": "Cancel a QUEUED or DISPATCHED job.\n\nReturns 400 if the job is not in a cancellable state,\n404 if the job does not exist, 422 if the ID format is invalid.",
        "operationId": "cancel_job_endpoint_api_v1_jobs__job_id__cancel_post",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jobs/{job_id}/result": {
      "get": {
        "tags": [
          "jobs"
        ],
        "summary": "Get Job Result",
        "description": "Return a presigned download URL for a completed job's result.\n\nThe job must be in COMPLETED status and have a non-null ``result_ref``.\nReturns 404 if the job does not exist, is not completed, or has no\nresult stored.\n\nNOTE: Owner-only access enforcement is planned for when a ``user_id``\ncolumn is added to the JobDispatch model. Currently, any authenticated\nuser can retrieve any job result (consistent with the existing\nlist/get/cancel endpoints).\n\nReturns 422 if the job ID format is invalid.",
        "operationId": "get_job_result_api_v1_jobs__job_id__result_get",
        "security": [
          {
            "HTTPBearer": []
          }
        ],
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Job Id"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResultResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/certs/issue": {
      "post": {
        "tags": [
          "certs",
          "certs"
        ],
        "summary": "Issue Certificate",
        "description": "Issue a signed node certificate.\n\nIf a CSR is not provided, generates a certificate and key pair\ndirectly using the CA. The CA certificate is also returned so the\nnode can verify the gateway's identity.\n\nAuthentication is expected to be handled upstream (e.g., via node JWT).",
        "operationId": "issue_certificate_api_v1_certs_issue_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CertIssueRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertIssueResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/certs/ca": {
      "get": {
        "tags": [
          "certs",
          "certs"
        ],
        "summary": "Get Ca Certificate",
        "description": "Download the CA certificate.\n\nThis endpoint is public -- it returns only the CA certificate\n(not the CA private key). Nodes need the CA cert to verify the\ngateway's server certificate during mTLS handshake.",
        "operationId": "get_ca_certificate_api_v1_certs_ca_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CACertResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/certs/renew": {
      "post": {
        "tags": [
          "certs",
          "certs"
        ],
        "summary": "Renew Certificate",
        "description": "Renew an expiring node certificate.\n\nValidates that the current certificate was issued by this CA,\nthen issues a fresh certificate for the same node_id.",
        "operationId": "renew_certificate_api_v1_certs_renew_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CertRenewRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertRenewResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Root Health",
        "description": "Root health check (alias for /api/v1/health).",
        "operationId": "root_health_health_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object",
                  "title": "Response Root Health Health Get"
                }
              }
            }
          }
        }
      }
    },
    "/version": {
      "get": {
        "summary": "Version",
        "description": "Return application version information.",
        "operationId": "version_version_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object",
                  "title": "Response Version Version Get"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BalanceResponse": {
        "properties": {
          "balance": {
            "type": "string",
            "title": "Balance"
          },
          "user_id": {
            "type": "string",
            "title": "User Id"
          }
        },
        "type": "object",
        "required": [
          "balance",
          "user_id"
        ],
        "title": "BalanceResponse",
        "description": "Credit balance response."
      },
      "CACertResponse": {
        "properties": {
          "ca_certificate": {
            "type": "string",
            "title": "Ca Certificate"
          }
        },
        "type": "object",
        "required": [
          "ca_certificate"
        ],
        "title": "CACertResponse",
        "description": "Response body for CA certificate download."
      },
      "CertIssueRequest": {
        "properties": {
          "node_id": {
            "type": "string",
            "title": "Node Id"
          },
          "csr_pem": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Csr Pem"
          }
        },
        "type": "object",
        "required": [
          "node_id"
        ],
        "title": "CertIssueRequest",
        "description": "Request body for certificate issuance."
      },
      "CertIssueResponse": {
        "properties": {
          "node_id": {
            "type": "string",
            "title": "Node Id"
          },
          "certificate": {
            "type": "string",
            "title": "Certificate"
          },
          "ca_certificate": {
            "type": "string",
            "title": "Ca Certificate"
          }
        },
        "type": "object",
        "required": [
          "node_id",
          "certificate",
          "ca_certificate"
        ],
        "title": "CertIssueResponse",
        "description": "Response body for certificate issuance."
      },
      "CertRenewRequest": {
        "properties": {
          "node_id": {
            "type": "string",
            "title": "Node Id"
          },
          "current_cert_pem": {
            "type": "string",
            "title": "Current Cert Pem"
          },
          "csr_pem": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Csr Pem"
          }
        },
        "type": "object",
        "required": [
          "node_id",
          "current_cert_pem"
        ],
        "title": "CertRenewRequest",
        "description": "Request body for certificate renewal."
      },
      "CertRenewResponse": {
        "properties": {
          "node_id": {
            "type": "string",
            "title": "Node Id"
          },
          "certificate": {
            "type": "string",
            "title": "Certificate"
          },
          "renewed": {
            "type": "boolean",
            "title": "Renewed",
            "default": true
          }
        },
        "type": "object",
        "required": [
          "node_id",
          "certificate"
        ],
        "title": "CertRenewResponse",
        "description": "Response body for certificate renewal."
      },
      "DeductRequest": {
        "properties": {
          "amount": {
            "type": "string",
            "title": "Amount"
          },
          "reference_id": {
            "type": "string",
            "title": "Reference Id"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          }
        },
        "type": "object",
        "required": [
          "amount",
          "reference_id"
        ],
        "title": "DeductRequest",
        "description": "Credit deduction request body."
      },
      "DispatchRequest": {
        "properties": {
          "job_type": {
            "type": "string",
            "maxLength": 100,
            "minLength": 1,
            "title": "Job Type",
            "description": "Job type (e.g. 'render', 'inference')"
          },
          "payload_ref": {
            "type": "string",
            "maxLength": 500,
            "minLength": 1,
            "title": "Payload Ref",
            "description": "Reference to the job payload (S3 URI, etc.)"
          }
        },
        "type": "object",
        "required": [
          "job_type",
          "payload_ref"
        ],
        "title": "DispatchRequest",
        "description": "Request body for job dispatch."
      },
      "DispatchResponse": {
        "properties": {
          "job_id": {
            "type": "string",
            "title": "Job Id"
          },
          "node_id": {
            "type": "string",
            "title": "Node Id"
          },
          "status": {
            "type": "string",
            "title": "Status"
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "node_id",
          "status"
        ],
        "title": "DispatchResponse",
        "description": "Response body for successful job dispatch."
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "HeartbeatRequest": {
        "properties": {
          "current_load": {
            "type": "number",
            "title": "Current Load",
            "default": 0.0
          },
          "metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Metadata"
          }
        },
        "type": "object",
        "title": "HeartbeatRequest",
        "description": "Request body for node heartbeat."
      },
      "HeartbeatResponse": {
        "properties": {
          "node_id": {
            "type": "string",
            "title": "Node Id"
          },
          "status": {
            "type": "string",
            "title": "Status"
          },
          "acknowledged": {
            "type": "boolean",
            "title": "Acknowledged",
            "default": true
          }
        },
        "type": "object",
        "required": [
          "node_id",
          "status"
        ],
        "title": "HeartbeatResponse",
        "description": "Response body for successful heartbeat."
      },
      "HistoryResponse": {
        "properties": {
          "entries": {
            "items": {
              "$ref": "#/components/schemas/LedgerEntryResponse"
            },
            "type": "array",
            "title": "Entries"
          },
          "count": {
            "type": "integer",
            "title": "Count"
          }
        },
        "type": "object",
        "required": [
          "entries",
          "count"
        ],
        "title": "HistoryResponse",
        "description": "Paginated credit history response."
      },
      "JobListResponse": {
        "properties": {
          "jobs": {
            "items": {
              "$ref": "#/components/schemas/JobResponse"
            },
            "type": "array",
            "title": "Jobs"
          },
          "count": {
            "type": "integer",
            "title": "Count"
          }
        },
        "type": "object",
        "required": [
          "jobs",
          "count"
        ],
        "title": "JobListResponse",
        "description": "Paginated job list response."
      },
      "JobResponse": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "node_id": {
            "type": "string",
            "title": "Node Id"
          },
          "job_type": {
            "type": "string",
            "title": "Job Type"
          },
          "payload_ref": {
            "type": "string",
            "title": "Payload Ref"
          },
          "status": {
            "type": "string",
            "title": "Status"
          },
          "result_ref": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Result Ref"
          },
          "error_message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error Message"
          },
          "retry_count": {
            "type": "integer",
            "title": "Retry Count"
          },
          "queued_at": {
            "type": "string",
            "title": "Queued At"
          },
          "dispatched_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Dispatched At"
          },
          "completed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Completed At"
          },
          "created_at": {
            "type": "string",
            "title": "Created At"
          },
          "updated_at": {
            "type": "string",
            "title": "Updated At"
          }
        },
        "type": "object",
        "required": [
          "id",
          "node_id",
          "job_type",
          "payload_ref",
          "status",
          "result_ref",
          "error_message",
          "retry_count",
          "queued_at",
          "dispatched_at",
          "completed_at",
          "created_at",
          "updated_at"
        ],
        "title": "JobResponse",
        "description": "Single job response schema."
      },
      "JobResultResponse": {
        "properties": {
          "job_id": {
            "type": "string",
            "title": "Job Id"
          },
          "download_url": {
            "type": "string",
            "title": "Download Url"
          },
          "expires_in": {
            "type": "integer",
            "title": "Expires In"
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "download_url",
          "expires_in"
        ],
        "title": "JobResultResponse",
        "description": "Response containing a presigned download URL for a job result."
      },
      "LedgerEntryResponse": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "amount": {
            "type": "string",
            "title": "Amount"
          },
          "direction": {
            "type": "string",
            "title": "Direction"
          },
          "source": {
            "type": "string",
            "title": "Source"
          },
          "reference_id": {
            "type": "string",
            "title": "Reference Id"
          },
          "balance_after": {
            "type": "string",
            "title": "Balance After"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "created_at": {
            "type": "string",
            "title": "Created At"
          }
        },
        "type": "object",
        "required": [
          "id",
          "amount",
          "direction",
          "source",
          "reference_id",
          "balance_after",
          "description",
          "created_at"
        ],
        "title": "LedgerEntryResponse",
        "description": "Single ledger entry in history responses."
      },
      "LoginRequest": {
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "title": "Email"
          },
          "password": {
            "type": "string",
            "title": "Password"
          }
        },
        "type": "object",
        "required": [
          "email",
          "password"
        ],
        "title": "LoginRequest",
        "description": "Login credentials payload."
      },
      "MessageResponse": {
        "properties": {
          "message": {
            "type": "string",
            "title": "Message"
          }
        },
        "type": "object",
        "required": [
          "message"
        ],
        "title": "MessageResponse",
        "description": "Generic message response."
      },
      "NodeRegisterRequest": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "public_key": {
            "type": "string",
            "title": "Public Key"
          },
          "capabilities": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Capabilities",
            "default": []
          },
          "metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Metadata"
          }
        },
        "type": "object",
        "required": [
          "name",
          "public_key"
        ],
        "title": "NodeRegisterRequest",
        "description": "Request body for node registration."
      },
      "NodeRegisterResponse": {
        "properties": {
          "node_id": {
            "type": "string",
            "title": "Node Id"
          },
          "challenge": {
            "type": "string",
            "title": "Challenge"
          },
          "token": {
            "type": "string",
            "title": "Token"
          },
          "status": {
            "type": "string",
            "title": "Status"
          }
        },
        "type": "object",
        "required": [
          "node_id",
          "challenge",
          "token",
          "status"
        ],
        "title": "NodeRegisterResponse",
        "description": "Response body for successful node registration."
      },
      "RefreshRequest": {
        "properties": {
          "refresh_token": {
            "type": "string",
            "title": "Refresh Token"
          }
        },
        "type": "object",
        "required": [
          "refresh_token"
        ],
        "title": "RefreshRequest",
        "description": "Token refresh payload."
      },
      "RegisterRequest": {
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "title": "Email"
          },
          "name": {
            "type": "string",
            "maxLength": 255,
            "minLength": 1,
            "title": "Name"
          },
          "password": {
            "type": "string",
            "minLength": 8,
            "title": "Password"
          }
        },
        "type": "object",
        "required": [
          "email",
          "name",
          "password"
        ],
        "title": "RegisterRequest",
        "description": "Registration payload."
      },
      "RegisterResponse": {
        "properties": {
          "user": {
            "$ref": "#/components/schemas/UserResponse"
          },
          "tokens": {
            "$ref": "#/components/schemas/TokenResponse"
          }
        },
        "type": "object",
        "required": [
          "user",
          "tokens"
        ],
        "title": "RegisterResponse",
        "description": "Registration response containing user info and tokens."
      },
      "TokenResponse": {
        "properties": {
          "access_token": {
            "type": "string",
            "title": "Access Token"
          },
          "refresh_token": {
            "type": "string",
            "title": "Refresh Token"
          },
          "token_type": {
            "type": "string",
            "title": "Token Type",
            "default": "bearer"
          }
        },
        "type": "object",
        "required": [
          "access_token",
          "refresh_token"
        ],
        "title": "TokenResponse",
        "description": "JWT token pair returned on successful authentication."
      },
      "UserResponse": {
        "properties": {
          "id": {
            "type": "string",
            "title": "Id"
          },
          "email": {
            "type": "string",
            "title": "Email"
          },
          "name": {
            "type": "string",
            "title": "Name"
          },
          "is_active": {
            "type": "boolean",
            "title": "Is Active"
          }
        },
        "type": "object",
        "required": [
          "id",
          "email",
          "name",
          "is_active"
        ],
        "title": "UserResponse",
        "description": "Public user representation (no sensitive fields)."
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    },
    "securitySchemes": {
      "HTTPBearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}