{ "openapi": "3.1.0", "info": { "title": "Xcelsior", "description": "Distributed GPU orchestration platform for AI/ML workloads. Canadian-first data sovereignty (PIPEDA/Law 25), automated trust scoring, Stripe Connect marketplace billing, and real-time GPU telemetry.\n\n**Authentication**: Bearer token via `Authorization: Bearer ` header.\n\n**Regions**: Canada-first with province-level filtering (ON, QC, BC, AB, etc.).\n\n**SDK**: Generate idiomatic Python/TypeScript SDKs with [Fern](https://buildwithfern.com).\n\n**LLM Integration**: See `/llms.txt` for AI agent–optimized documentation.\n\nThis published OpenAPI document contains the public developer surface only. Account settings, internal worker, admin, maintenance, and callback endpoints are intentionally omitted.", "contact": { "name": "Xcelsior", "url": "https://xcelsior.ca/", "email": "admin@xcelsior.ca" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "2.3.0" }, "servers": [ { "url": "https://xcelsior.ca", "description": "Production" }, { "url": "http://localhost:9500", "description": "Development" } ], "paths": { "/api/artifacts/upload": { "post": { "tags": [ "Artifacts" ], "summary": "Api Request Upload", "description": "Get a presigned upload URL for an artifact.", "operationId": "api_request_upload_api_artifacts_upload_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/artifacts/download": { "post": { "tags": [ "Artifacts" ], "summary": "Api Request Download", "description": "Get a presigned download URL for an artifact.", "operationId": "api_request_download_api_artifacts_download_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/artifacts/{job_id}": { "get": { "tags": [ "Artifacts" ], "summary": "Api List Artifacts", "description": "List all artifacts for a job.", "operationId": "api_list_artifacts_api_artifacts__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/artifacts/{job_id}/expiry": { "get": { "tags": [ "Artifacts" ], "summary": "Api Artifact Expiry", "description": "Get expiry/cleanup dates for artifacts of a given job.\n\nReturns each artifact with its created_at and estimated expiry date\nbased on the configured retention policy.", "operationId": "api_artifact_expiry_api_artifacts__job_id__expiry_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "tags": [ "Auth" ], "summary": "Oauth Authorization Server Metadata", "operationId": "oauth_authorization_server_metadata__well_known_oauth_authorization_server_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/oauth/authorize": { "get": { "tags": [ "Auth" ], "summary": "Oauth Authorize", "operationId": "oauth_authorize_oauth_authorize_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/oauth/token": { "post": { "tags": [ "Auth" ], "summary": "Oauth Token", "operationId": "oauth_token_oauth_token_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/oauth/device/authorize": { "post": { "tags": [ "Auth" ], "summary": "Oauth Device Authorize", "operationId": "oauth_device_authorize_oauth_device_authorize_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Api Auth Register", "description": "Register a new user with email and password.\n\nCreates an account and sends a verification email. The user must verify\ntheir email before they can log in.", "operationId": "api_auth_register_api_auth_register_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Api Auth Login", "description": "Authenticate with email and password.\n\nReturns a Bearer token valid for 30 days.\nIf MFA is enabled, returns mfa_required=True with a challenge_id instead.", "operationId": "api_auth_login_api_auth_login_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Api Auth Me", "description": "Get the currently authenticated user's profile.\n\nRequires Authorization: Bearer header.", "operationId": "api_auth_me_api_auth_me_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Api Auth Logout", "description": "Logout — invalidate session and clear cookie.", "operationId": "api_auth_logout_api_auth_logout_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/billing/wallet/{customer_id}": { "get": { "tags": [ "Billing" ], "summary": "Api Get Wallet", "description": "Get credit wallet balance and status.", "operationId": "api_get_wallet_api_billing_wallet__customer_id__get", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Customer Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/payment-intent": { "post": { "tags": [ "Billing" ], "summary": "Api Create Payment Intent", "description": "Create a Stripe PaymentIntent for depositing compute credits.\n\nReturns client_secret for front-end Stripe Elements confirmation.\nOn payment_intent.succeeded webhook the wallet is credited automatically.", "operationId": "api_create_payment_intent_api_billing_payment_intent_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/paypal/enabled": { "get": { "tags": [ "Billing" ], "summary": "Api Paypal Enabled", "description": "Check whether PayPal is configured.", "operationId": "api_paypal_enabled_api_billing_paypal_enabled_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/billing/paypal/create-order": { "post": { "tags": [ "Billing" ], "summary": "Api Paypal Create Order", "description": "Create a PayPal order for depositing compute credits.", "operationId": "api_paypal_create_order_api_billing_paypal_create_order_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalCreateOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/paypal/capture-order": { "post": { "tags": [ "Billing" ], "summary": "Api Paypal Capture Order", "description": "Capture a PayPal order and credit the wallet.", "operationId": "api_paypal_capture_order_api_billing_paypal_capture_order_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayPalCaptureRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/wallet/{customer_id}/deposit": { "post": { "tags": [ "Billing" ], "summary": "Api Deposit", "description": "Deposit credits into a customer wallet.", "operationId": "api_deposit_api_billing_wallet__customer_id__deposit_post", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Customer Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/wallet/{customer_id}/history": { "get": { "tags": [ "Billing" ], "summary": "Api Wallet History", "description": "Get transaction history for a wallet.", "operationId": "api_wallet_history_api_billing_wallet__customer_id__history_get", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Customer Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/wallet/{customer_id}/depletion": { "get": { "tags": [ "Billing" ], "summary": "Api Wallet Depletion", "description": "Get real-time balance depletion projection.\n\nReturns burn rate, seconds-to-zero, per-instance cost breakdown,\nand alert thresholds (T-30min, T-5min, T-0).", "operationId": "api_wallet_depletion_api_billing_wallet__customer_id__depletion_get", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Customer Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/usage/{customer_id}": { "get": { "tags": [ "Billing" ], "summary": "Api Usage Summary", "description": "Get usage summary for a customer.", "operationId": "api_usage_summary_api_billing_usage__customer_id__get", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Customer Id" } }, { "name": "period_start", "in": "query", "required": false, "schema": { "type": "number", "default": 0, "title": "Period Start" } }, { "name": "period_end", "in": "query", "required": false, "schema": { "type": "number", "default": 0, "title": "Period End" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/invoice/{customer_id}": { "get": { "tags": [ "Billing" ], "summary": "Api Generate Invoice", "description": "Generate an AI Compute Access Fund–aligned invoice.", "operationId": "api_generate_invoice_api_billing_invoice__customer_id__get", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Customer Id" } }, { "name": "customer_name", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Customer Name" } }, { "name": "period_start", "in": "query", "required": false, "schema": { "type": "number", "default": 0, "title": "Period Start" } }, { "name": "period_end", "in": "query", "required": false, "schema": { "type": "number", "default": 0, "title": "Period End" } }, { "name": "tax_rate", "in": "query", "required": false, "schema": { "type": "number", "default": 0.13, "title": "Tax Rate" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/invoices/{customer_id}": { "get": { "tags": [ "Billing" ], "summary": "Api List Invoices", "description": "List past invoices for a customer (monthly summaries).\n\nGenerates monthly invoice stubs for the last N months showing\ntotal spend, tax, job count, and top GPUs used.", "operationId": "api_list_invoices_api_billing_invoices__customer_id__get", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Customer Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 12, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/billing/invoice/{customer_id}/download": { "get": { "tags": [ "Billing" ], "summary": "Api Download Invoice", "description": "Download an invoice as CSV or plain-text PDF-style document.\n\nFormats: csv (spreadsheet-ready), txt (printable receipt).", "operationId": "api_download_invoice_api_billing_invoice__customer_id__download_get", "parameters": [ { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Customer Id" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "default": "csv", "title": "Format" } }, { "name": "period_start", "in": "query", "required": false, "schema": { "type": "number", "default": 0, "title": "Period Start" } }, { "name": "period_end", "in": "query", "required": false, "schema": { "type": "number", "default": 0, "title": "Period End" } }, { "name": "tax_rate", "in": "query", "required": false, "schema": { "type": "number", "default": 0.13, "title": "Tax Rate" } }, { "name": "customer_name", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Customer Name" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/pricing/estimate": { "post": { "tags": [ "Billing" ], "summary": "Api Estimate Cost", "description": "Estimate job cost with AI Compute Access Fund rebate preview.\n\nFrom REPORT_FEATURE_2.md: --estimate-rebate / simulate=true", "operationId": "api_estimate_cost_api_pricing_estimate_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/pricing/reference": { "get": { "tags": [ "Billing" ], "summary": "Api Reference Pricing", "description": "Get reference GPU pricing table in CAD.", "operationId": "api_reference_pricing_api_pricing_reference_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v2/billing/auto-topup": { "get": { "tags": [ "Billing" ], "summary": "Api Billing Get Topup", "description": "Get current auto-top-up configuration.", "operationId": "api_billing_get_topup_api_v2_billing_auto_topup_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } }, "post": { "tags": [ "Billing" ], "summary": "Api Billing Configure Topup", "description": "Configure wallet auto-top-up via Stripe.", "operationId": "api_billing_configure_topup_api_v2_billing_auto_topup_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoTopupConfig" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/inference": { "post": { "tags": [ "Inference v2" ], "summary": "Api V1 Inference Sync", "description": "Synchronous inference endpoint (OpenAI-compatible path).\n\nSubmits an inference request and polls for results up to 30 seconds.\nIf stream=true, returns SSE text/event-stream with token deltas.", "operationId": "api_v1_inference_sync_v1_inference_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1InferenceRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/inference/async": { "post": { "tags": [ "Inference v2" ], "summary": "Api V1 Inference Async", "description": "Asynchronous inference — returns job_id immediately for polling.", "operationId": "api_v1_inference_async_v1_inference_async_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1InferenceRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/inference/{job_id}": { "get": { "tags": [ "Inference v2" ], "summary": "Api V1 Inference Poll", "description": "Poll for inference results by job_id.", "operationId": "api_v1_inference_poll_v1_inference__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/inference/endpoints": { "get": { "tags": [ "Inference v2" ], "summary": "Api Inference List Endpoints", "description": "List inference endpoints for the current user.", "operationId": "api_inference_list_endpoints_api_v2_inference_endpoints_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } }, "post": { "tags": [ "Inference v2" ], "summary": "Api Inference Create Endpoint", "description": "Create a serverless inference endpoint.\n\nIf min_workers >= 1, a worker container is provisioned immediately.\nBilling is real-time from credits (per-second compute + per-token inference).", "operationId": "api_inference_create_endpoint_api_v2_inference_endpoints_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InferenceEndpointCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/inference/endpoints/{endpoint_id}": { "get": { "tags": [ "Inference v2" ], "summary": "Api Inference Get Endpoint", "description": "Get inference endpoint details.", "operationId": "api_inference_get_endpoint_api_v2_inference_endpoints__endpoint_id__get", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Endpoint Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Inference v2" ], "summary": "Api Inference Delete Endpoint", "description": "Delete an inference endpoint.", "operationId": "api_inference_delete_endpoint_api_v2_inference_endpoints__endpoint_id__delete", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Endpoint Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/inference/endpoints/{endpoint_id}/health": { "get": { "tags": [ "Inference v2" ], "summary": "Api Inference Endpoint Health", "description": "Get health status for an inference endpoint and its workers.", "operationId": "api_inference_endpoint_health_api_v2_inference_endpoints__endpoint_id__health_get", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Endpoint Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/inference/endpoints/{endpoint_id}/usage": { "get": { "tags": [ "Inference v2" ], "summary": "Api Inference Endpoint Usage", "description": "Get usage stats for an inference endpoint.", "operationId": "api_inference_endpoint_usage_api_v2_inference_endpoints__endpoint_id__usage_get", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Endpoint Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "Inference v2" ], "summary": "Api Openai Chat Completions", "description": "OpenAI-compatible chat completions endpoint.\n\nRoutes to a serverless inference endpoint running the requested model.", "operationId": "api_openai_chat_completions_v1_chat_completions_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/instance": { "post": { "tags": [ "Instances" ], "summary": "Api Submit Instance", "description": "Submit a job to the queue or directly assign to a host.\n\nIf host_id is provided (marketplace launch), the job is assigned directly\nto that host and container start is attempted immediately. Otherwise,\nthe job is queued and process_queue runs to find a host.", "operationId": "api_submit_instance_instance_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobIn" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/instances": { "get": { "tags": [ "Instances" ], "summary": "Api List Instances", "description": "List jobs. Optional filter by status.", "operationId": "api_list_instances_instances_get", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/instance/{job_id}": { "get": { "tags": [ "Instances" ], "summary": "Api Get Instance", "description": "Get a specific instance by ID, enriched with connection info.", "operationId": "api_get_instance_instance__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/instances/{job_id}/cancel": { "post": { "tags": [ "Instances" ], "summary": "Api Cancel Instance", "description": "Cancel a running or queued instance. For interactive instances, stops the container.", "operationId": "api_cancel_instance_instances__job_id__cancel_post", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/instances/{job_id}/logs": { "get": { "tags": [ "Instances" ], "summary": "Api Instance Logs", "description": "Get buffered log lines for a job (non-streaming).\n\nReturns the last `limit` log lines. Tries in-memory buffer first,\nfalls back to persistent job_logs table in PG.\nFor real-time streaming, use `/jobs/{job_id}/logs/stream` (SSE).", "operationId": "api_instance_logs_instances__job_id__logs_get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/tiers": { "get": { "tags": [ "Instances" ], "summary": "Api List Tiers", "description": "List all priority tiers with their multipliers.", "operationId": "api_list_tiers_tiers_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/marketplace/search": { "get": { "tags": [ "Marketplace" ], "summary": "Api Marketplace Search", "description": "Search marketplace listings with filters and sorting.", "operationId": "api_marketplace_search_marketplace_search_get", "parameters": [ { "name": "gpu_model", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gpu Model" } }, { "name": "min_vram", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Min Vram" } }, { "name": "max_price", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Max Price" } }, { "name": "province", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Province" } }, { "name": "country", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country" } }, { "name": "min_reputation", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Min Reputation" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "type": "string", "default": "price", "title": "Sort By" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/marketplace": { "get": { "tags": [ "Marketplace" ], "summary": "Api Get Marketplace", "description": "Browse marketplace listings.", "operationId": "api_get_marketplace_marketplace_get", "parameters": [ { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean", "default": true, "title": "Active Only" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/marketplace/stats": { "get": { "tags": [ "Marketplace" ], "summary": "Api Marketplace Stats", "description": "Marketplace aggregate stats.", "operationId": "api_marketplace_stats_marketplace_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v2/marketplace/search": { "post": { "tags": [ "Marketplace v2" ], "summary": "Api Marketplace Search", "description": "Search available GPU offers with filters.", "operationId": "api_marketplace_search_api_v2_marketplace_search_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceSearchParams" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/marketplace/spot-prices": { "get": { "tags": [ "Marketplace v2" ], "summary": "Api Marketplace Spot Prices", "description": "Get current spot prices for all GPU models.", "operationId": "api_marketplace_spot_prices_api_v2_marketplace_spot_prices_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v2/marketplace/spot-prices/{gpu_model}/history": { "get": { "tags": [ "Marketplace v2" ], "summary": "Api Marketplace Spot History", "description": "Get spot price history for a GPU model.", "operationId": "api_marketplace_spot_history_api_v2_marketplace_spot_prices__gpu_model__history_get", "parameters": [ { "name": "gpu_model", "in": "path", "required": true, "schema": { "type": "string", "title": "Gpu Model" } }, { "name": "hours", "in": "query", "required": false, "schema": { "type": "integer", "default": 24, "title": "Hours" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/marketplace/stats": { "get": { "tags": [ "Marketplace v2" ], "summary": "Api Marketplace Stats V2", "description": "Get marketplace aggregate statistics.", "operationId": "api_marketplace_stats_v2_api_v2_marketplace_stats_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/api/v2/marketplace/reservations": { "post": { "tags": [ "Marketplace v2" ], "summary": "Api Marketplace Create Reservation", "description": "Create a reserved instance commitment.", "operationId": "api_marketplace_create_reservation_api_v2_marketplace_reservations_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReservationCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/marketplace/reservations/{reservation_id}": { "delete": { "tags": [ "Marketplace v2" ], "summary": "Api Marketplace Cancel Reservation", "description": "Cancel a reserved instance commitment early.\n\nComputes early termination fee: remaining_months * monthly_rate * 50%.", "operationId": "api_marketplace_cancel_reservation_api_v2_marketplace_reservations__reservation_id__delete", "parameters": [ { "name": "reservation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Reservation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/volumes": { "get": { "tags": [ "Volumes" ], "summary": "Api Volume List", "description": "List volumes owned by the current user.", "operationId": "api_volume_list_api_v2_volumes_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } }, "post": { "tags": [ "Volumes" ], "summary": "Api Volume Create", "description": "Create a new persistent volume. Billed in real-time from credits.", "operationId": "api_volume_create_api_v2_volumes_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeCreate" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/volumes/{volume_id}": { "get": { "tags": [ "Volumes" ], "summary": "Api Volume Get", "description": "Get volume details.", "operationId": "api_volume_get_api_v2_volumes__volume_id__get", "parameters": [ { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Volume Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "delete": { "tags": [ "Volumes" ], "summary": "Api Volume Delete", "description": "Delete a volume. Must not have active attachments.", "operationId": "api_volume_delete_api_v2_volumes__volume_id__delete", "parameters": [ { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Volume Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/volumes/{volume_id}/attach": { "post": { "tags": [ "Volumes" ], "summary": "Api Volume Attach", "description": "Attach a volume to a running instance.", "operationId": "api_volume_attach_api_v2_volumes__volume_id__attach_post", "parameters": [ { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Volume Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VolumeAttachRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v2/volumes/{volume_id}/detach": { "post": { "tags": [ "Volumes" ], "summary": "Api Volume Detach", "description": "Detach a volume from its current instance.", "operationId": "api_volume_detach_api_v2_volumes__volume_id__detach_post", "parameters": [ { "name": "volume_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Volume Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "RegisterRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "password": { "type": "string", "title": "Password" }, "name": { "type": "string", "title": "Name", "default": "" }, "role": { "type": "string", "title": "Role", "default": "submitter" } }, "type": "object", "required": [ "email", "password" ], "title": "RegisterRequest" }, "PayPalCaptureRequest": { "properties": { "customer_id": { "type": "string", "title": "Customer Id" }, "order_id": { "type": "string", "title": "Order Id" } }, "type": "object", "required": [ "customer_id", "order_id" ], "title": "PayPalCaptureRequest" }, "UploadRequest": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "filename": { "type": "string", "title": "Filename" }, "artifact_type": { "type": "string", "title": "Artifact Type", "default": "job_output" }, "residency_policy": { "type": "string", "title": "Residency Policy", "default": "canada_only" } }, "type": "object", "required": [ "job_id", "filename" ], "title": "UploadRequest" }, "DepositRequest": { "properties": { "amount_cad": { "type": "number", "title": "Amount Cad" }, "description": { "type": "string", "title": "Description", "default": "Credit deposit" } }, "type": "object", "required": [ "amount_cad" ], "title": "DepositRequest" }, "PayPalCreateOrderRequest": { "properties": { "customer_id": { "type": "string", "title": "Customer Id" }, "amount_cad": { "type": "number", "title": "Amount Cad" } }, "type": "object", "required": [ "customer_id", "amount_cad" ], "title": "PayPalCreateOrderRequest" }, "ReservationCreate": { "properties": { "gpu_model": { "type": "string", "title": "Gpu Model" }, "gpu_count": { "type": "integer", "title": "Gpu Count", "default": 1 }, "period_months": { "type": "integer", "title": "Period Months", "default": 1 } }, "type": "object", "required": [ "gpu_model" ], "title": "ReservationCreate" }, "InferenceEndpointCreate": { "properties": { "model_name": { "type": "string", "title": "Model Name" }, "gpu_type": { "type": "string", "title": "Gpu Type", "default": "" }, "region": { "type": "string", "title": "Region", "default": "ca-east" }, "docker_image": { "type": "string", "title": "Docker Image", "default": "xcelsior/vllm:latest" }, "min_workers": { "type": "integer", "title": "Min Workers", "default": 0 }, "max_workers": { "type": "integer", "title": "Max Workers", "default": 3 }, "max_batch_size": { "type": "integer", "title": "Max Batch Size", "default": 8 }, "max_concurrent": { "type": "integer", "title": "Max Concurrent", "default": 4 }, "scaledown_window_sec": { "type": "integer", "title": "Scaledown Window Sec", "default": 300 }, "mode": { "type": "string", "title": "Mode", "default": "sync" }, "health_endpoint": { "type": "string", "title": "Health Endpoint", "default": "/health" }, "api_format": { "type": "string", "title": "Api Format", "default": "openai" } }, "type": "object", "required": [ "model_name" ], "title": "InferenceEndpointCreate" }, "VolumeAttachRequest": { "properties": { "instance_id": { "type": "string", "title": "Instance Id" }, "mount_path": { "type": "string", "title": "Mount Path", "default": "/workspace" }, "mode": { "type": "string", "title": "Mode", "default": "rw" } }, "type": "object", "required": [ "instance_id" ], "title": "VolumeAttachRequest" }, "JobIn": { "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1, "title": "Name" }, "vram_needed_gb": { "type": "number", "minimum": 0.0, "title": "Vram Needed Gb", "default": 0 }, "priority": { "type": "integer", "maximum": 10.0, "minimum": 0.0, "title": "Priority", "default": 0 }, "tier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tier" }, "num_gpus": { "type": "integer", "maximum": 64.0, "minimum": 1.0, "title": "Num Gpus", "default": 1 }, "host_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Host Id" }, "gpu_model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Gpu Model" }, "nfs_server": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfs Server" }, "nfs_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfs Path" }, "nfs_mount_point": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Nfs Mount Point" }, "image": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Image" }, "interactive": { "type": "boolean", "title": "Interactive", "default": true }, "command": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Command" }, "ssh_port": { "type": "integer", "maximum": 65535.0, "minimum": 1.0, "title": "Ssh Port", "default": 22 }, "max_bid": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0.0 }, { "type": "null" } ], "title": "Max Bid" } }, "type": "object", "required": [ "name" ], "title": "JobIn" }, "ChatCompletionRequest": { "properties": { "model": { "type": "string", "title": "Model" }, "messages": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Messages" }, "max_tokens": { "type": "integer", "maximum": 32768.0, "minimum": 1.0, "title": "Max Tokens", "default": 512 }, "temperature": { "type": "number", "maximum": 2.0, "minimum": 0.0, "title": "Temperature", "default": 1.0 }, "stream": { "type": "boolean", "title": "Stream", "default": false } }, "type": "object", "required": [ "model" ], "title": "ChatCompletionRequest", "description": "OpenAI-compatible chat completion request." }, "V1InferenceRequest": { "properties": { "model": { "type": "string", "title": "Model", "description": "Model name or HuggingFace repo" }, "inputs": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "string" } ], "title": "Inputs", "description": "Text input(s) for inference" }, "max_tokens": { "type": "integer", "maximum": 8192.0, "minimum": 1.0, "title": "Max Tokens", "default": 512 }, "temperature": { "type": "number", "maximum": 2.0, "minimum": 0.0, "title": "Temperature", "default": 1.0 }, "stream": { "type": "boolean", "title": "Stream", "description": "Stream response via SSE", "default": false } }, "type": "object", "required": [ "model", "inputs" ], "title": "V1InferenceRequest", "description": "OpenAI-compatible inference request for /v1/inference." }, "DownloadRequest": { "properties": { "job_id": { "type": "string", "title": "Job Id" }, "filename": { "type": "string", "title": "Filename" }, "artifact_type": { "type": "string", "title": "Artifact Type", "default": "job_output" } }, "type": "object", "required": [ "job_id", "filename" ], "title": "DownloadRequest" }, "LoginRequest": { "properties": { "email": { "type": "string", "title": "Email" }, "password": { "type": "string", "title": "Password" } }, "type": "object", "required": [ "email", "password" ], "title": "LoginRequest" }, "PaymentIntentRequest": { "properties": { "customer_id": { "type": "string", "title": "Customer Id" }, "amount_cad": { "type": "number", "title": "Amount Cad" }, "description": { "type": "string", "title": "Description", "default": "Compute credits" } }, "type": "object", "required": [ "customer_id", "amount_cad" ], "title": "PaymentIntentRequest" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "AutoTopupConfig": { "properties": { "enabled": { "type": "boolean", "title": "Enabled", "default": true }, "amount_cad": { "type": "number", "title": "Amount Cad", "default": 25.0 }, "threshold_cad": { "type": "number", "title": "Threshold Cad", "default": 5.0 }, "stripe_payment_method_id": { "type": "string", "title": "Stripe Payment Method Id", "default": "" } }, "type": "object", "title": "AutoTopupConfig" }, "MarketplaceSearchParams": { "properties": { "gpu_model": { "type": "string", "title": "Gpu Model", "default": "" }, "min_vram_gb": { "type": "number", "title": "Min Vram Gb", "default": 0 }, "max_price_cents": { "type": "integer", "title": "Max Price Cents", "default": 0 }, "region": { "type": "string", "title": "Region", "default": "" }, "canada_only": { "type": "boolean", "title": "Canada Only", "default": false }, "sort_by": { "type": "string", "title": "Sort By", "default": "price" }, "limit": { "type": "integer", "title": "Limit", "default": 50 } }, "type": "object", "title": "MarketplaceSearchParams" }, "VolumeCreate": { "properties": { "name": { "type": "string", "title": "Name" }, "size_gb": { "type": "integer", "title": "Size Gb", "default": 50 }, "region": { "type": "string", "title": "Region", "default": "ca-east" }, "encrypted": { "type": "boolean", "title": "Encrypted", "default": true } }, "type": "object", "required": [ "name" ], "title": "VolumeCreate" }, "EstimateRequest": { "properties": { "gpu_model": { "type": "string", "title": "Gpu Model", "default": "RTX 4090" }, "duration_hours": { "type": "number", "title": "Duration Hours", "default": 1.0 }, "spot": { "type": "boolean", "title": "Spot", "default": false }, "sovereignty": { "type": "boolean", "title": "Sovereignty", "default": false }, "is_canadian": { "type": "boolean", "title": "Is Canadian", "default": true } }, "type": "object", "title": "EstimateRequest" }, "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" } } }, "tags": [ { "name": "Artifacts", "description": "Presigned upload/download URLs for model weights, checkpoints, outputs." }, { "name": "Auth" }, { "name": "Billing", "description": "Wallet management, invoicing, CAF exports, refunds. Credit-first CAD billing." }, { "name": "Inference v2" }, { "name": "Instances" }, { "name": "Marketplace", "description": "Rig listings, browsing, and marketplace billing." }, { "name": "Marketplace v2" }, { "name": "Volumes" } ] }