{
  "openapi": "3.1.0",
  "info": {
    "title": "TRC Developer API & Unified AI/Storage Gateway",
    "version": "1.0.0",
    "summary": "OpenAI- and Anthropic-compatible multi-provider AI gateway, 50 GB–50 TB Cloud Storage Vault API, Whisper transcription, game tileset generation, AI music, and public page blueprints on trc.inc.",
    "description": "Official REST API v1 for TRC (https://www.trc.inc), operated by Relationship Constitution, LLC. Authenticate with a SHA-256 hashed, scoped developer key (`Authorization: Bearer trc_...` or `x-trc-api-key: trc_...`) minted at https://www.trc.inc/developer/api, or verify live inference without a card using the capped public evaluator key `Bearer trc_eval_public_v1` on `POST /ai/deepseek/chat/completions` (`model: deepseek-flash`). Billable calls draw from included monthly subscription compute credits first, then pre-funded TRC Wallet balance (10% managed wallet gateway fee), returning structured HTTP 402 (`INSUFFICIENT_FUNDS`) instead of surprise post-paid overages. Bring-Your-Own-Key (BYOK) across supported model providers carries $0.00 (0%) TRC markup.",
    "termsOfService": "https://www.trc.inc/terms-and-conditions",
    "contact": {
      "name": "TRC Developer Platform (Relationship Constitution, LLC)",
      "url": "https://www.trc.inc/docs/api"
    }
  },
  "externalDocs": {
    "description": "TRC Full Technical Documentation & Quickstarts",
    "url": "https://www.trc.inc/docs"
  },
  "servers": [
    {
      "url": "https://api.trc.inc/api/v1",
      "description": "TRC Production API v1 Gateway"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    },
    {
      "TrcApiKeyHeader": []
    }
  ],
  "tags": [
    {
      "name": "AI Model Gateway",
      "description": "Drop-in OpenAI Chat Completions and native Anthropic Messages API across deepseek, google, openai, anthropic, alibaba, kimi, xai, and together."
    },
    {
      "name": "Cloud Storage Vault",
      "description": "Programmatic S3/Backblaze B2 object storage (50 GB Free to 50 TB) with streaming binary uploads up to 2 GB."
    },
    {
      "name": "Creative Media & Voice",
      "description": "AI image generation, chroma-key sliced 2D game sprite tilesets, Whisper transcription, AI music generation, SoundBites, and GIF search."
    },
    {
      "name": "Identity & Page Blueprints",
      "description": "Authenticated developer identity, public user handles, and sandboxed custom page blueprints."
    }
  ],
  "paths": {
    "/pricing": {
      "get": {
        "tags": ["AI Model Gateway"],
        "operationId": "getPublicPricingCatalog",
        "summary": "Public live token pricing, UTC off-peak schedule, media rates, and tier specs",
        "description": "Public endpoint (no API key required). Derived directly from the runtime billing engine (`providerPricingService.js` and `developerBillingService.js`) so published docs, `/docs/proof`, and live billing never drift.",
        "security": [],
        "responses": {
          "200": {
            "description": "Curated public pricing, Sovereign Cloud tiers, Storage Vault quotas, and zero-card evaluator specification",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PublicPricingCatalog" }
              }
            }
          }
        }
      }
    },
    "/models": {
      "get": {
        "tags": ["AI Model Gateway"],
        "operationId": "listGatewayModels",
        "summary": "List available AI models and live token pricing",
        "description": "Public endpoint (no API key required; optional `Bearer trc_...` with `models:use` also accepted). Returns curated supported providers, model IDs, context windows, and per-1M token pricing (including automatic 50% DeepSeek off-peak discounts).",
        "security": [],
        "responses": {
          "200": {
            "description": "Live catalog of gateway models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "type": "string", "const": "list" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ModelDescriptor" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/ai/{provider}/models": {
      "get": {
        "tags": ["AI Model Gateway"],
        "operationId": "listProviderModels",
        "summary": "List available models and live token pricing for a specific provider",
        "description": "Requires scope `models:use`. Compatible with OpenAI SDK `client.models.list()` when `baseURL` is set to `https://api.trc.inc/api/v1/ai/{provider}`.",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["deepseek", "google", "openai", "anthropic", "alibaba", "kimi", "xai", "together"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog of models for the requested provider",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "object": { "type": "string", "const": "list" },
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/ModelDescriptor" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/UnauthorizedError" }
        }
      }
    },
    "/ai/{provider}/chat/completions": {
      "post": {
        "tags": ["AI Model Gateway"],
        "operationId": "createChatCompletion",
        "summary": "OpenAI-compatible Chat Completions across 8 frontier providers",
        "description": "Requires scope `models:use` (or capped public evaluator key `Bearer trc_eval_public_v1` on `provider=deepseek` with `model: deepseek-flash`, `stream: false`, `max_tokens <= 256`). 100% drop-in compatible with the official OpenAI Node, Python, Go, and Rust SDKs by setting `baseURL` to `https://api.trc.inc/api/v1/ai/{provider}`.",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["deepseek", "google", "openai", "anthropic", "alibaba", "kimi", "xai", "together"]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Standard OpenAI ChatCompletion JSON or `text/event-stream` SSE chunks when `stream: true`.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/UnauthorizedError" },
          "402": { "$ref": "#/components/responses/InsufficientFundsError" },
          "429": { "$ref": "#/components/responses/RateLimitError" }
        }
      }
    },
    "/ai/anthropic/messages": {
      "post": {
        "tags": ["AI Model Gateway"],
        "operationId": "createAnthropicMessage",
        "summary": "Native Anthropic Messages API passthrough",
        "description": "Requires scope `models:use`. Compatible with `@anthropic-ai/sdk` (`baseURL: https://api.trc.inc/api/v1/ai/anthropic`), preserving extended thinking blocks, tool_use, and prompt caching.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["model", "max_tokens", "messages"],
                "properties": {
                  "model": { "type": "string", "examples": ["claude-sonnet-4-6", "claude-opus-4-8", "claude-haiku-4-5"] },
                  "max_tokens": { "type": "integer", "minimum": 1 },
                  "stream": { "type": "boolean", "default": false },
                  "system": { "type": ["string", "array"] },
                  "messages": { "type": "array", "items": { "type": "object" } }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Anthropic Message response or SSE stream" },
          "401": { "$ref": "#/components/responses/UnauthorizedError" },
          "402": { "$ref": "#/components/responses/InsufficientFundsError" }
        }
      }
    },
    "/ai/images/generate": {
      "post": {
        "tags": ["Creative Media & Voice"],
        "operationId": "generateImage",
        "summary": "Generate high-resolution AI images",
        "description": "Requires scope `images:use` or `models:use`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": { "type": "string" },
                  "aspectRatio": { "type": "string", "examples": ["1:1", "16:9", "9:16"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Generated image URLs and metadata" },
          "402": { "$ref": "#/components/responses/InsufficientFundsError" }
        }
      }
    },
    "/ai/images/tileset": {
      "post": {
        "tags": ["Creative Media & Voice"],
        "operationId": "generateSpriteTileset",
        "summary": "Generate chroma-key sliced 2D game sprite sheets and tilesets",
        "description": "Requires scope `images:use` or `models:use`. Produces both the master sprite sheet and individually sliced transparent PNG frame URLs.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": { "type": "string" },
                  "columns": { "type": "integer", "default": 4 },
                  "rows": { "type": "integer", "default": 4 }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Master sprite sheet URL and sliced tile array" },
          "402": { "$ref": "#/components/responses/InsufficientFundsError" }
        }
      }
    },
    "/storage/upload": {
      "post": {
        "tags": ["Cloud Storage Vault"],
        "operationId": "uploadVaultFile",
        "summary": "Stream binary or multipart files (up to 2 GB) to Cloud Storage Vault",
        "description": "Requires scope `storage:write`. Streams directly to persistent Backblaze B2 / S3-compatible storage within your 50 GB – 50 TB plan quota.",
        "parameters": [
          {
            "name": "folder",
            "in": "query",
            "required": false,
            "description": "Optional logical folder prefix (e.g. `datasets/prod` or `backups/nightly`).",
            "schema": { "type": "string" }
          },
          {
            "name": "x-file-name",
            "in": "header",
            "required": false,
            "description": "Target filename when streaming raw `application/octet-stream` payloads.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": { "type": "string", "format": "binary" }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": { "type": "string", "format": "binary" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Stored object key, byte size, and retrieval metadata" },
          "401": { "$ref": "#/components/responses/UnauthorizedError" },
          "413": { "description": "Payload exceeds 2 GB single-stream ceiling or plan storage quota" }
        }
      }
    },
    "/storage/files": {
      "get": {
        "tags": ["Cloud Storage Vault"],
        "operationId": "listVaultFiles",
        "summary": "List stored Cloud Storage Vault objects and signed download URLs",
        "description": "Requires scope `storage:read`.",
        "parameters": [
          {
            "name": "folder",
            "in": "query",
            "required": false,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 50, "maximum": 500 }
          }
        ],
        "responses": {
          "200": { "description": "Paginated array of stored vault objects with signed URLs" },
          "401": { "$ref": "#/components/responses/UnauthorizedError" }
        }
      }
    },
    "/storage/usage": {
      "get": {
        "tags": ["Cloud Storage Vault"],
        "operationId": "getVaultUsage",
        "summary": "Inspect live Cloud Storage Vault byte consumption and plan ceiling",
        "description": "Requires scope `storage:read`. Reports used bytes, plan quota (50 GB Free up to 50 TB), and remaining capacity.",
        "responses": {
          "200": {
            "description": "Live storage quota telemetry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "usedBytes": { "type": "integer" },
                    "quotaBytes": { "type": "integer" },
                    "planTier": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/transcribe": {
      "post": {
        "tags": ["Creative Media & Voice"],
        "operationId": "transcribeAudio",
        "summary": "Transcribe speech audio with TRC Whisper",
        "description": "Requires scope `whisper:use`.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["file"],
                "properties": {
                  "file": { "type": "string", "format": "binary" },
                  "language": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Transcript text and segment timestamps" },
          "402": { "$ref": "#/components/responses/InsufficientFundsError" }
        }
      }
    },
    "/audio/generate": {
      "post": {
        "tags": ["Creative Media & Voice"],
        "operationId": "generateMusicTrack",
        "summary": "Start asynchronous full-track AI music generation",
        "description": "Requires scope `music:use`. Poll `/audio/generate/{jobId}/status` for completion.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": { "type": "string" },
                  "lyrics": { "type": "string" },
                  "instrumental": { "type": "boolean", "default": false }
                }
              }
            }
          }
        },
        "responses": {
          "202": { "description": "Queued generation job identifier" },
          "402": { "$ref": "#/components/responses/InsufficientFundsError" }
        }
      }
    },
    "/audio/generate/{jobId}/status": {
      "get": {
        "tags": ["Creative Media & Voice"],
        "operationId": "getMusicGenerationStatus",
        "summary": "Poll AI music generation status and retrieve master audio URL",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Job status and completed track URLs" }
        }
      }
    },
    "/soundbites/clips": {
      "post": {
        "tags": ["Creative Media & Voice"],
        "operationId": "createSoundBiteClip",
        "summary": "Publish a short-form SoundBite audio clip",
        "description": "Requires scope `soundbites:use`.",
        "responses": {
          "200": { "description": "Created SoundBite clip metadata" },
          "402": { "$ref": "#/components/responses/InsufficientFundsError" }
        }
      }
    },
    "/gifs/search": {
      "get": {
        "tags": ["Creative Media & Voice"],
        "operationId": "searchGifs",
        "summary": "Search reaction GIFs",
        "description": "Requires scope `gifs:use`.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20 } }
        ],
        "responses": {
          "200": { "description": "Matching GIF results" }
        }
      }
    },
    "/gifs/trending": {
      "get": {
        "tags": ["Creative Media & Voice"],
        "operationId": "listTrendingGifs",
        "summary": "Fetch trending GIFs",
        "description": "Requires scope `gifs:use`.",
        "responses": {
          "200": { "description": "Trending GIF list" }
        }
      }
    },
    "/me": {
      "get": {
        "tags": ["Identity & Page Blueprints"],
        "operationId": "getAuthenticatedProfile",
        "summary": "Retrieve authenticated account & key scope metadata",
        "description": "Requires scope `profile:read`.",
        "responses": {
          "200": { "description": "Account identity, active plan tier, and granted key scopes" }
        }
      }
    },
    "/users/{handle}": {
      "get": {
        "tags": ["Identity & Page Blueprints"],
        "operationId": "getUserByHandle",
        "summary": "Resolve public profile metadata by handle",
        "description": "Requires scope `profile:read`.",
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Public profile record" },
          "404": { "description": "Handle not found" }
        }
      }
    },
    "/pages/{ownerType}/{ownerId}/{pageType}": {
      "get": {
        "tags": ["Identity & Page Blueprints"],
        "operationId": "getPageBlueprint",
        "summary": "Read sanitized public custom page blueprint & widget slots",
        "description": "Requires scope `pages:read`. See https://www.trc.inc/developer/spec for the full widget manifest schema.",
        "parameters": [
          { "name": "ownerType", "in": "path", "required": true, "schema": { "type": "string", "enum": ["user", "partner"] } },
          { "name": "ownerId", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "pageType", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Sanitized page blueprint JSON" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "trc_live_*",
        "description": "Scoped SHA-256 hashed developer key (`Authorization: Bearer trc_...`) minted at https://www.trc.inc/developer/api. Available scopes: `models:use`, `images:use`, `storage:read`, `storage:write`, `whisper:use`, `soundbites:use`, `music:use`, `gifs:use`, `telephony:call`, `telephony:numbers`, `sms:send`, `profile:read`, `pages:read`."
      },
      "TrcApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-trc-api-key",
        "description": "Alternative header passing `trc_...` directly."
      }
    },
    "schemas": {
      "PublicPricingCatalog": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "const": true },
          "object": { "type": "string", "const": "pricing_catalog" },
          "asOf": { "type": "string", "format": "date-time" },
          "pricingVersion": { "type": "string" },
          "currency": { "type": "string", "const": "USD" },
          "billingPolicy": { "type": "object" },
          "deepseekOffPeakWindow": { "type": "object" },
          "models": { "type": "array", "items": { "type": "object" } },
          "flatProductsUsd": { "type": "object" },
          "sovereignCloudTiers": { "type": "array", "items": { "type": "object" } },
          "cloudStorageVault": { "type": "object" },
          "proofEvaluator": { "type": "object" }
        }
      },
      "ModelDescriptor": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "examples": ["deepseek-flash", "deepseek-reasoner", "gemini-3.8-flash", "claude-sonnet-4-6", "qwen3.5-omni-flash"] },
          "provider": { "type": "string", "examples": ["deepseek", "google", "anthropic", "openai", "alibaba"] },
          "inputPer1MUsd": { "type": "number" },
          "outputPer1MUsd": { "type": "number" },
          "cachedInputPer1MUsd": { "type": "number" },
          "offPeakDiscountApplied": { "type": "boolean" }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": { "type": "string", "examples": ["deepseek-flash", "gemini-3.8-flash", "gpt-4o-mini", "claude-sonnet-4-6"] },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["role", "content"],
              "properties": {
                "role": { "type": "string", "enum": ["system", "developer", "user", "assistant", "tool"] },
                "content": { "type": ["string", "array"] }
              }
            }
          },
          "temperature": { "type": "number", "minimum": 0, "maximum": 2 },
          "max_tokens": { "type": "integer" },
          "stream": { "type": "boolean", "default": false },
          "tools": { "type": "array", "items": { "type": "object" } },
          "response_format": { "type": "object" }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string", "const": "chat.completion" },
          "created": { "type": "integer" },
          "model": { "type": "string" },
          "choices": { "type": "array", "items": { "type": "object" } },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": { "type": "integer" },
              "completion_tokens": { "type": "integer" },
              "total_tokens": { "type": "integer" }
            }
          },
          "trc_billing_proof": {
            "type": "object",
            "description": "Returned on zero-card evaluator calls (`Bearer trc_eval_public_v1`) with exact prompt/completion token counts, UTC pricing window, $0 BYOK provider base cost, and +10% managed wallet cost."
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      }
    },
    "responses": {
      "UnauthorizedError": {
        "description": "Missing, revoked, or insufficiently scoped `trc_...` API key.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
          }
        }
      },
      "InsufficientFundsError": {
        "description": "Included monthly plan credits and TRC Wallet balance are exhausted (`INSUFFICIENT_FUNDS`). Top up at https://www.trc.inc/developer/api or attach a $0-markup BYOK provider key.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "example": {
              "error": {
                "code": "INSUFFICIENT_FUNDS",
                "message": "Included plan allowance and TRC Wallet balance reached $0.00. No post-paid overage was charged."
              }
            }
          }
        }
      },
      "RateLimitError": {
        "description": "Per-key request rate limit exceeded.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
          }
        }
      }
    }
  }
}