{ "openapi": "3.0.0", "info": { "title": "Trading Card API", "description": "Trading Card API provides comprehensive access to trading card data including cards, sets, players, teams, and related information. Built with Laravel and following JSON:API specification.\n\n### Rate-limit headers\n\nEvery throttled response — successful ones included, not just a 429 — carries `X-RateLimit-Limit` (the quota for the current window), `X-RateLimit-Remaining` (requests left in it) and `X-RateLimit-Reset` (the Unix timestamp at which the window resets). The window length is not published as a header: derive it from `X-RateLimit-Reset` rather than assuming a value, since the quota and window both vary by credential (anonymous, OAuth/PAT, per-client override, internal pool). `Retry-After` is added only on a 429. All of these headers are named in `Access-Control-Expose-Headers`, so browser-side clients can read them cross-origin.", "contact": { "name": "Trading Card API Support", "url": "https://tradingcardapi.com", "email": "support@tradingcardapi.com" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" }, "version": "0.10.61" }, "servers": [ { "url": "https://api.tradingcardapi.com", "description": "Production API Server" }, { "url": "https://api.tradingcardapi.dev:8243", "description": "Development API Server" }, { "url": "http://localhost:8000", "description": "Local Development Server" } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Liveness/readiness healthcheck (infrastructure)", "description": "Infrastructure healthcheck for load balancers and uptime monitors. Returns 200 when the database and cache are reachable, or 503 when a dependency check fails. Unauthenticated, unthrottled, and excluded from API usage logging. Not a public API feature. The `checks.billing` key is advisory only: it reports `degraded` when billing or lifecycle-email configuration is incomplete and never affects the status code.", "operationId": "63ca574ccc7f0d914cdced2f70f30b57", "responses": { "200": { "description": "All dependency checks passed; the app is ready to serve traffic", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string", "example": "0.2.84" }, "checks": { "properties": { "database": { "type": "string", "example": "ok" }, "cache": { "type": "string", "example": "ok" }, "billing": { "type": "string", "example": "ok" } }, "type": "object" } }, "type": "object" } } } }, "503": { "description": "At least one dependency check failed; the app is not ready to serve traffic", "content": { "application/json": { "schema": { "properties": { "status": { "type": "string", "example": "error" }, "version": { "type": "string", "example": "0.2.84" }, "checks": { "properties": { "database": { "type": "string", "example": "error" }, "cache": { "type": "string", "example": "ok" }, "billing": { "type": "string", "example": "degraded" } }, "type": "object" } }, "type": "object" } } } } }, "security": [] } }, "/internal/analytics/sales-readiness": { "get": { "tags": [ "Internal" ], "summary": "Sales readiness report (internal)", "description": "Returns the analyze:sales-readiness data-coverage report. Requires the 'internal' OAuth scope. Use format=json (default) for the structured payload or format=table for the rendered text table.", "operationId": "a20392e057aad225fe5406f204dd466a", "parameters": [ { "name": "format", "in": "query", "description": "Output format: json (default) or table", "required": false, "schema": { "type": "string", "default": "json", "enum": [ "json", "table" ] } }, { "name": "years", "in": "query", "description": "Number of most recent years to include in year coverage (must be a positive integer)", "required": false, "schema": { "type": "integer", "default": 10 } }, { "name": "months", "in": "query", "description": "Number of most recent months for the update-cadence window (positive integer)", "required": false, "schema": { "type": "integer", "default": 12 } } ], "responses": { "200": { "description": "Report returned successfully. With format=json (default) the structured data-coverage report object; with format=table a rendered fixed-width text table.", "content": { "application/vnd.api+json": { "schema": { "description": "Sales-readiness data-coverage report (format=json).", "properties": { "overview": { "description": "Top-line set/card totals and publication rate.", "type": "object" }, "update_cadence": { "description": "Publish cadence over the requested recent-month window.", "type": "object" }, "genre_breakdown": { "description": "Per-genre published-set and on-card coverage.", "type": "array", "items": { "type": "object" } }, "year_coverage": { "description": "Per-year set/card coverage for the requested recent years.", "type": "array", "items": { "type": "object" } }, "data_completeness": { "description": "Completeness metrics across required fields and relationships.", "type": "object" }, "base_set_completeness": { "description": "Base-set checklist completeness.", "type": "array", "items": { "type": "object" } }, "workflow_status": { "description": "Counts of sets by workflow step and status.", "type": "object" }, "throughput": { "description": "Recent processing throughput metrics.", "type": "object" } }, "type": "object" } }, "text/plain": { "schema": { "description": "Rendered fixed-width report table (format=table).", "type": "string" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing the 'internal' scope" }, "422": { "description": "Invalid format, years, or months parameter" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] } }, "/webhooks/stripe": { "post": { "tags": [ "Webhooks" ], "summary": "Stripe webhook receiver (infrastructure)", "description": "Receives Stripe webhook events. Unauthenticated — the Stripe-Signature header verified against the configured signing secret is the authentication. Returns 200 on accepted (including duplicate and unknown event types) and 400 on signature verification failure. Not a public API feature.", "operationId": "2589850c7e0297e155a6008aa494ec86", "responses": { "200": { "description": "Event accepted (or duplicate / unknown type acknowledged)" }, "400": { "description": "Signature verification failed or payload malformed" } }, "security": [] } }, "/v1/user/api-key": { "get": { "tags": [ "Authentication" ], "summary": "Get the authenticated user's API key (masked)", "description": "Returns masked metadata for the authenticated end user's single opaque API key. Never returns the plaintext key. If no key exists yet, `data` is null.", "operationId": "415efd3426e338bd12f85ce3dcb20d19", "responses": { "200": { "description": "Masked key metadata (or null when no key exists)" }, "401": { "description": "Unauthenticated — no token, an invalid/expired token, or a Passport personal-access token (rejected outright at the auth layer since the opaque-key cutover)" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which authenticates fine on the data endpoints but may not read its owner's API-key metadata" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Authentication" ], "summary": "Regenerate the authenticated user's API key", "description": "Revokes the user's existing API key (if any) and issues a new opaque `tc_live_` key. Returns the plaintext key exactly once, alongside masked metadata. The previous key stops authenticating immediately.", "operationId": "bbaf3d857b202c7ea3597e37a7d18fb7", "responses": { "201": { "description": "New key issued; plaintext returned exactly once" }, "401": { "description": "Unauthenticated — no token, an invalid/expired token, or a Passport personal-access token (rejected outright at the auth layer since the opaque-key cutover)" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which authenticates fine on the data endpoints but may not rotate its owner's API key" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Authentication" ], "summary": "Revoke the authenticated user's API key", "description": "Revokes the user's existing opaque `tc_live_` key (if any) without minting a replacement. The key stops authenticating immediately. Idempotent: a no-op 204 when the user has no live key. To rotate the key instead, POST the same path.", "operationId": "0d362dcb8ed4ff5855600c9bec1dd0d1", "responses": { "204": { "description": "Key revoked (or no-op when no live key exists)" }, "401": { "description": "Unauthenticated — no token, an invalid/expired token, or a Passport personal-access token (rejected outright at the auth layer since the opaque-key cutover)" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which authenticates fine on the data endpoints but may not revoke its owner's API key" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] } }, "/v1/attributes": { "get": { "tags": [ "Attributes v1" ], "summary": "Get all card attributes (v1)", "description": "Retrieve a paginated list of all card attributes (autographs, variations, etc.)", "operationId": "8ec5febc0c1fe69e4bd6bdb8004f5ac8", "parameters": [ { "name": "name", "in": "query", "description": "Filter by attribute name. The value is an exact match by default. Prefix it with `like:` for a case-insensitive substring match (for example `like:Auto`). Inside a `like:` value, `%` and `_` are matched literally rather than acting as SQL wildcards.", "required": false, "schema": { "type": "string", "example": "like:Auto" } }, { "name": "limit", "in": "query", "description": "Number of attributes per page", "required": false, "schema": { "type": "integer", "example": 25, "default": 25 } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of attributes retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } }, "included": { "type": "array", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Attributes v1" ], "summary": "Create a new attribute (v1)", "description": "Create a new card attribute (autograph, variation, etc.)", "operationId": "fb15304ee62a73602f1f291051e1ea9b", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "attributes" }, "attributes": { "required": [ "attribute", "name" ], "properties": { "attribute": { "type": "string", "example": "AU" }, "name": { "type": "string", "example": "Autograph" }, "description": { "type": "string", "example": "Player's signature on card", "nullable": true }, "color": { "type": "string", "example": "#FF0000", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Attribute created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Attribute" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/attributes/{id}": { "get": { "tags": [ "Attributes v1" ], "summary": "Get a specific attribute (v1)", "description": "Retrieve detailed information about a specific card attribute by ID", "operationId": "6b9c4b39c0f0d9918e6574a64671c9bf", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the attribute to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Attribute retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Attribute" }, "included": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Attribute not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Attributes v1" ], "summary": "Delete an attribute (v1)", "description": "Delete an existing card attribute", "operationId": "57546411183527ec6130768b713d39c8", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the attribute to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Attribute deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Attribute not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Attributes v1" ], "summary": "Update an attribute (v1)", "description": "Update an existing card attribute", "operationId": "f1fe67f8bc10bd3085451786847fdf83", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the attribute to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "attributes" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "attribute": { "type": "string", "example": "AU" }, "name": { "type": "string", "example": "Autograph" }, "description": { "type": "string", "example": "Player's signature on card", "nullable": true }, "color": { "type": "string", "example": "#FF0000", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Attribute updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Attribute" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Attribute not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/internal/audit-logs": { "get": { "tags": [ "Internal" ], "summary": "List audit log events (internal)", "description": "Retrieve audit log events with optional filtering by entity, event type, and date range. Defaults to last 30 days when no date filters are provided. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "c379be061c1c8d4e466dfe49282f757f", "parameters": [ { "name": "filter[auditable_type]", "in": "query", "description": "Filter by entity type (e.g. set, card, player, team)", "required": false, "schema": { "type": "string", "enum": [ "set", "card", "player", "team", "playerteam" ] } }, { "name": "filter[auditable_id]", "in": "query", "description": "Filter by entity UUID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[event_type]", "in": "query", "description": "Filter by event type", "required": false, "schema": { "type": "string" } }, { "name": "filter[start_date]", "in": "query", "description": "Filter events on or after this date (ISO 8601)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[end_date]", "in": "query", "description": "Filter events on or before this date (ISO 8601)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "per_page", "in": "query", "description": "Number of results per page (default 50, max 500)", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 500 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "List of audit log events retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer": [] } ], "x-internal": true }, "post": { "tags": [ "Internal" ], "summary": "Create an audit log event (internal)", "description": "Record a new audit log event. Supports polymorphic association with any entity. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "e15afdf4431435dcffd55c2783ab450e", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "audit_logs" }, "attributes": { "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "example": "agent_spawned", "maxLength": 50 }, "auditable_type": { "type": "string", "example": "set", "nullable": true, "enum": [ "set", "card", "player", "team", "playerteam" ] }, "auditable_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "agent_id": { "type": "string", "example": "agent-abc-123", "nullable": true, "maxLength": 100 }, "data": { "type": "object", "example": { "step": "populate", "status": "started" }, "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Audit log event created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/AuditLog" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer": [] } ], "x-internal": true } }, "/v1/billing/checkout": { "post": { "tags": [ "Billing" ], "summary": "Create a Stripe Checkout Session for self-service subscribe (v1)", "description": "Creates a subscription-mode Stripe Checkout Session for the authenticated caller's billing account (lazily creating the account and Stripe customer on first use) and returns the hosted session URL. The `plan` selects the Stripe price; optional success_url/cancel_url must match the configured trusted-origin allowlist.", "operationId": "7d86f1fe351434ffc063b2f4c445c3b2", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "required": [ "plan" ], "properties": { "plan": { "description": "The plan slug to subscribe to. Must be one of the plans configured for the API (at launch: `starter` or `pro`).", "type": "string", "example": "starter" }, "success_url": { "description": "Optional. Where Stripe returns the user after a completed checkout. Its origin must be in the configured trusted-origin allowlist.", "type": "string", "format": "uri", "example": "https://app.tradingcardapi.com/account/billing?checkout=success" }, "cancel_url": { "description": "Optional. Where Stripe returns the user if they abandon checkout. Its origin must be in the configured trusted-origin allowlist.", "type": "string", "format": "uri", "example": "https://app.tradingcardapi.com/account/billing?checkout=cancel" } }, "type": "object" } } } }, "responses": { "200": { "description": "Checkout session created", "content": { "application/vnd.api+json": { "schema": { "properties": { "url": { "type": "string", "format": "uri", "example": "https://checkout.stripe.com/c/pay/cs_test_abc123" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which may not subscribe its owner" }, "422": { "description": "Unknown plan, or success_url/cancel_url origin not in the trusted allowlist" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Stripe checkout session creation failed" } }, "security": [ { "bearer": [] } ] } }, "/v1/billing/portal": { "post": { "tags": [ "Billing" ], "summary": "Create a Stripe Customer Portal session (v1)", "description": "Creates a Stripe Billing Portal session for the authenticated caller's billing account (lazily creating the account and Stripe customer on first use) and returns the hosted session URL. An optional return_url must match the configured trusted-origin allowlist.", "operationId": "9da473251356c545ef3b54f12ae51c31", "requestBody": { "required": false, "content": { "application/vnd.api+json": { "schema": { "properties": { "return_url": { "description": "Optional. Where Stripe returns the user after the portal session. Its origin must be in the configured trusted-origin allowlist.", "type": "string", "format": "uri", "example": "https://app.tradingcardapi.com/account/billing" } }, "type": "object" } } } }, "responses": { "200": { "description": "Portal session created", "content": { "application/vnd.api+json": { "schema": { "properties": { "url": { "type": "string", "format": "uri", "example": "https://billing.stripe.com/session/test_abc123" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which may not open its owner's billing portal" }, "422": { "description": "return_url origin not in the trusted allowlist" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "description": "Stripe portal session creation failed" } }, "security": [ { "bearer": [] } ] } }, "/v1/brands": { "get": { "tags": [ "Brands v1" ], "summary": "Get all brands (v1)", "description": "Retrieve a list of all trading card brands", "operationId": "b5c13cd4dc464d5cc75e230a9389ac27", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include. Supported: sets", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of brands retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Brands v1" ], "summary": "Create a new brand (v1)", "description": "Create a new trading card brand", "operationId": "6429aaddf9163ecf305e4f674658cf20", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "brands" }, "attributes": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Topps" }, "description": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Brand created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Brand" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/brands/{id}": { "get": { "tags": [ "Brands v1" ], "summary": "Get a specific brand (v1)", "description": "Retrieve detailed information about a specific brand by ID", "operationId": "4817d34cd19ecc819eb226c0ecbab4ae", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the brand to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include. Supported: sets", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brand retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Brand" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Brand not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Brands v1" ], "summary": "Delete a brand (v1)", "description": "Delete an existing brand", "operationId": "2122ec5bb25f226e85cd2781921a72ff", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the brand to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Brand deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Brand not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Brands v1" ], "summary": "Update a brand (v1)", "description": "Update an existing brand", "operationId": "9f4488e671173dee1fc26e6f4adcd04f", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the brand to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "brands" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "Topps" }, "description": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Brand updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Brand" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Brand not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/cards": { "get": { "tags": [ "Cards v1" ], "summary": "Get all cards (v1)", "description": "Retrieve a paginated list of all trading cards in the system", "operationId": "8ca38beaebdf245e5abd2b1572fbc931", "parameters": [ { "name": "filter[set_id]", "in": "query", "description": "Filter cards by set UUID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[player_id]", "in": "query", "description": "Filter cards by player UUID. Returns every card the player appears on, both directly and via a player-team.", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include (set,oncard,attributes,children)", "required": false, "schema": { "type": "string", "example": "set,oncard" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (max 100, default 25)", "required": false, "schema": { "type": "integer", "example": 25, "default": 25, "maximum": 100 } } ], "responses": { "200": { "description": "List of cards retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "included": { "type": "array", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidQueryParameter" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Cards v1" ], "summary": "Create a new card (v1)", "description": "Create a new trading card record", "operationId": "efa130a8b82341ef6847a5de8fa4e319", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "cards" }, "attributes": { "properties": { "number": { "description": "Card number within the set", "type": "string", "example": "23" }, "serial_number": { "type": "string", "example": "001/100", "nullable": true }, "image_uuid": { "description": "UUID reference for card image", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "title": { "type": "string", "example": "Rookie Card", "nullable": true }, "notes": { "type": "string", "nullable": true } }, "type": "object" }, "relationships": { "properties": { "set": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "sets" }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "type": "object" }, "oncard": { "properties": { "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "players", "teams", "playerteams" ] }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Card created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Card" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/cards/{id}": { "get": { "tags": [ "Cards v1" ], "summary": "Get a specific card (v1)", "description": "Retrieve detailed information about a specific trading card by ID", "operationId": "456f44a8ffffdc3baa3faf7a6d244cb8", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the card to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include (set,oncard,attributes,children)", "required": false, "schema": { "type": "string", "example": "set,oncard" } } ], "responses": { "200": { "description": "Card retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Card" }, "included": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Card not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Cards v1" ], "summary": "Delete a card (v1)", "description": "Delete an existing trading card record", "operationId": "278451b0f3c3f00589bc9906b28ca802", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the card to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Card deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Card not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Cards v1" ], "summary": "Update a card (v1)", "description": "Update an existing trading card record", "operationId": "2f0fc273bb9af4187b12aee73d3ae538", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the card to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "cards" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "number": { "type": "string", "example": "23" }, "serial_number": { "type": "string", "example": "001/100", "nullable": true }, "image_uuid": { "description": "UUID reference for card image", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "title": { "type": "string", "example": "Rookie Card", "nullable": true }, "notes": { "type": "string", "nullable": true }, "attributes": { "description": "Extra attributes for the card", "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "value": { "type": "string" } }, "type": "object" } }, "field_overrides": { "description": "Fields not inherited from parent (parallel cards only)", "type": "array", "items": { "type": "string", "enum": [ "title", "number", "description", "is_rookie", "serial", "section" ] }, "nullable": true } }, "type": "object" }, "relationships": { "properties": { "set": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "sets" }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "type": "object" }, "oncard": { "properties": { "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "players", "teams", "playerteams" ] }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Card updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Card" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Card not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/card-images": { "get": { "tags": [ "Card Images" ], "summary": "List all card images", "description": "List all card images", "operationId": "2a7d4cfb9c74af20ae41018f0603a1dd", "parameters": [ { "name": "include", "in": "query", "description": "Include related resources (card)", "schema": { "type": "string", "example": "card" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (default 50, max 100)", "required": false, "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "List of card images" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Card Images" ], "summary": "Upload a new card image", "description": "Upload a new card image", "operationId": "4fccd2edbe32ff6db21fcd7bd96010e0", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "file", "data" ], "properties": { "file": { "description": "Image file (JPEG, PNG, or WebP, max 10MB, max 4000x4000px)", "type": "string", "format": "binary" }, "data": { "description": "JSON:API formatted data", "type": "string", "format": "json", "example": "{\"type\":\"card_images\",\"attributes\":{\"card_id\":\"uuid\",\"image_type\":\"front\"}}" } }, "type": "object" } } } }, "responses": { "201": { "description": "Image uploaded successfully" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/card-images/{id}": { "get": { "tags": [ "Card Images" ], "summary": "Get a specific card image", "description": "Get a specific card image", "operationId": "27b3ff616feca812948f312954cba8fd", "parameters": [ { "name": "id", "in": "path", "description": "Card image UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Include related resources (card)", "schema": { "type": "string", "example": "card" } } ], "responses": { "200": { "description": "Card image details" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Card image not found" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Card Images" ], "summary": "Delete a card image", "description": "Delete a card image", "operationId": "7b904c4ced4f620b7ae2a5790b1ad0a7", "parameters": [ { "name": "id", "in": "path", "description": "Card image UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Image deleted successfully" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Card image not found" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Card Images" ], "summary": "Update a card image", "description": "Update a card image", "operationId": "d1228e8f6f985626c326bbeae9d35aa4", "parameters": [ { "name": "id", "in": "path", "description": "Card image UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Image updated successfully" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Card image not found" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/card-images/{card_image}/download": { "get": { "tags": [ "Card Images" ], "summary": "Download the actual image file", "description": "Download/stream the actual image file", "operationId": "08c3fe8e8c603db64791a1f0ec89365a", "parameters": [ { "name": "card_image", "in": "path", "description": "Card image UUID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "size", "in": "query", "description": "Image size variant. Sizes configured in config/images.php (default: small/medium/large)", "required": false, "schema": { "type": "string", "default": "original", "enum": [ "original", "small", "medium", "large" ] } } ], "responses": { "200": { "description": "Image file stream", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Card image or variant not found" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/card-image-batches": { "post": { "tags": [ "Card Images" ], "summary": "Upload multiple card images in a batch", "description": "Accepts up to 50 images per request. Returns immediately with a batch ID for polling status. The legacy POST /v1/card-images/bulk URL is a deprecated alias for this endpoint (slated for removal in v2).", "operationId": "4375c878adf00f7fa97619fca412279f", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "files", "data" ], "properties": { "files[]": { "description": "Image files (max 50, each max 10MB, JPEG/PNG/WebP)", "type": "array", "items": { "type": "string", "format": "binary" } }, "data": { "description": "JSON:API formatted data with mappings", "type": "string", "format": "json", "example": "{\"type\":\"bulk_card_images\",\"attributes\":{\"mappings\":[...]}}" } }, "type": "object" } } } }, "responses": { "202": { "description": "Batch accepted for processing" }, "401": { "description": "The caller identity could not be resolved, so the batch would have no owner and would be unreadable by anyone. The request is rejected instead of accepted." }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/card-image-batches/{card_image_batch}": { "get": { "tags": [ "Card Images" ], "summary": "Get bulk upload batch status", "description": "Returns bulk upload batch status and progress. Poll to track progress. The legacy GET /v1/card-images/bulk/{batch_id} URL is a deprecated alias for this endpoint (slated for removal in v2).", "operationId": "694da72a49d582f58fad7b00cbc1f3c9", "parameters": [ { "name": "card_image_batch", "in": "path", "description": "Batch UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Batch status" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Batch not found. Batches are scoped to the caller that created them, so a batch belonging to another caller is indistinguishable from one that does not exist." }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/founding-slots/remaining": { "get": { "tags": [ "Billing" ], "summary": "Get the remaining founding-customer slots", "description": "Returns the number of founding-customer slots still available as a single derived count (capacity minus the billing accounts currently trialing or active). Public and unauthenticated — it exposes only the aggregate remaining count for the marketing-site indicator, no per-user state. Throttled by the default anonymous rate limit.", "operationId": "00171b503ed84c4c3f90877ebcd316aa", "responses": { "200": { "description": "The remaining founding-slot count, the configured capacity, and `gate_enabled` — whether the founding cap is being enforced at all. When `gate_enabled` is false the cap has been lifted and both `remaining` and `capacity` are null (there is no limit to report); clients should hide the scarcity indicator rather than treat null as an error." }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/v1/genres": { "get": { "tags": [ "Genres v1" ], "summary": "Get all genres (v1)", "description": "Retrieve a paginated list of all trading card genres", "operationId": "c3b85b59e35b870910a760b6eb1e00b5", "parameters": [ { "name": "limit", "in": "query", "description": "Number of genres per page", "required": false, "schema": { "type": "integer", "example": 25, "default": 25 } }, { "name": "name", "in": "query", "description": "Filter by genre name. The value is an exact match by default. Prefix it with `like:` for a case-insensitive substring match (for example `like:Base`). Inside a `like:` value, `%` and `_` are matched literally rather than acting as SQL wildcards.", "required": false, "schema": { "type": "string", "example": "like:Base" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "description": "Filter genres by soft-delete state. Use 'deleted' to list only soft-deleted genres or 'active' for live genres (the default).", "required": false, "schema": { "type": "string", "enum": [ "active", "deleted" ] } } ], "responses": { "200": { "description": "List of genres retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Genre" } } }, "type": "object" } } } }, "400": { "description": "Invalid filter parameter" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Genres v1" ], "summary": "Create a new genre (v1)", "description": "Create a new trading card genre, restoring if previously soft-deleted", "operationId": "fc0d0c44d5c6aa63bf5b7ceebf14e4d7", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "genres" }, "attributes": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Baseball" }, "description": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Genre created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Genre" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/genres/{id}": { "get": { "tags": [ "Genres v1" ], "summary": "Get a specific genre (v1)", "description": "Retrieve detailed information about a specific genre by ID", "operationId": "5490dedf2128bdd1ff8cc97ea8400a23", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the genre to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } }, { "name": "include_trashed", "in": "query", "description": "When true, a soft-deleted genre is returnable by id. Defaults to false (soft-deleted genres 404).", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Genre retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Genre" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Genre not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Genres v1" ], "summary": "Delete a genre (v1)", "description": "Soft delete an existing genre record", "operationId": "1c6920f7e9e1616403f8f5119bda7daf", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the genre to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Genre archived successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Genre not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Genres v1" ], "summary": "Update a genre (v1)", "description": "Update an existing genre record", "operationId": "83bfd421da8817e17192f78d1bf46a91", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the genre to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "genres" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "Baseball" }, "description": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Genre updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Genre" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Genre not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/invites/validate": { "post": { "tags": [ "Authentication" ], "summary": "Validate a signup invite code (v1)", "description": "Reports whether an invite code may currently be used to create an account. Public (no authentication) so the marketing site's signup page can check the link a visitor arrived on before rendering a form.\n\nThis endpoint CONSUMES NOTHING and reserves nothing: a `valid` verdict means the code is live and had a use left at the moment of the check, not that a use — or a founding slot — is held for the caller. Enforcement happens again at `POST /v1/signup`.\n\nRejections carry a distinguishable `code`: `invite_invalid` (unknown, revoked, or pinned to a different address), `invite_expired` (410, renewable), or `invite_exhausted` (every use spent). The code must be sent in the JSON body; a code in the query string is ignored, since a query string is recorded by proxies and travels onward in `Referer`. Throttled by `throttle:invite-validate` per IP and per code so the endpoint is not a brute-force oracle.", "operationId": "74df67bdd187855eba057e795d338796", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "invite-validations" }, "attributes": { "required": [ "code" ], "properties": { "code": { "type": "string", "example": "FOUNDING-2026" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Invite code is currently valid" }, "410": { "description": "Invite code has expired" }, "422": { "description": "Invite code is missing, unknown, revoked, or fully used" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/internal/invites": { "get": { "tags": [ "Internal" ], "summary": "List signup invites (internal)", "description": "Lists issued invites with their label, pinned email, use counts, expiry and revocation state. Internal endpoint: requires the `internal` OAuth scope.\n\nThe plaintext code is NEVER returned here — it is surfaced exactly once at issuance and only its SHA-256 hash is stored.", "operationId": "2a5d81fb05bb42b2cd4d83b08e32dd2c", "responses": { "200": { "description": "Invites retrieved successfully" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing the `internal` OAuth scope" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ], "x-internal": true }, "post": { "tags": [ "Internal" ], "summary": "Issue a signup invite (internal)", "description": "Mints a new invite code and returns its plaintext EXACTLY ONCE — only the SHA-256 hash is persisted, so the code cannot be retrieved afterward. Internal endpoint: requires the `internal` OAuth scope.\n\nAll attributes are optional; an empty body issues a single-use, unpinned invite with the configured default TTL. Supply `max_uses` for a cohort code, `email` to pin the invite to one address, and `expires_at: null` for an invite that never expires.\n\nThe `code` attribute seeds a caller-supplied plaintext instead of minting one. It exists for the cutover from the marketing site's single shared code, so links already in a cohort's hands keep working when enforcement deploys.", "operationId": "e075e010bde093603654018fdf93ef2d", "requestBody": { "required": false, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "invites" }, "attributes": { "properties": { "label": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "max_uses": { "type": "integer", "example": 1 }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "code": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Invite issued; plaintext code returned once" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Missing the `internal` OAuth scope" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ], "x-internal": true } }, "/v1/manufacturers": { "get": { "tags": [ "Manufacturers v1" ], "summary": "Get all manufacturers (v1)", "description": "Retrieve a list of all trading card manufacturers", "operationId": "02ad7606ce333077033623c3e12a5a7c", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of manufacturers retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Manufacturer" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Manufacturers v1" ], "summary": "Create a new manufacturer (v1)", "description": "Create a new trading card manufacturer", "operationId": "1819d0360d6988a56483e681910cc26c", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "manufacturers" }, "attributes": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Topps Company" }, "description": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Manufacturer created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Manufacturer" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/manufacturers/{id}": { "get": { "tags": [ "Manufacturers v1" ], "summary": "Get a specific manufacturer (v1)", "description": "Retrieve detailed information about a specific manufacturer by ID", "operationId": "ff850ede26139ea8a468e244900ae790", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the manufacturer to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Manufacturer retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Manufacturer" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Manufacturer not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Manufacturers v1" ], "summary": "Delete a manufacturer (v1)", "description": "Delete an existing manufacturer", "operationId": "f1ba36f8fd07a19f439b48905e44d39d", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the manufacturer to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Manufacturer deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Manufacturer not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Manufacturers v1" ], "summary": "Update a manufacturer (v1)", "description": "Update an existing manufacturer", "operationId": "eb350d511e2b7609ff7c2771f75ee800", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the manufacturer to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "manufacturers" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "Topps Company" }, "description": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Manufacturer updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Manufacturer" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Manufacturer not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/me": { "get": { "tags": [ "Authentication" ], "summary": "Get the authenticated user (v1)", "description": "Returns the currently authenticated user as a JSON:API resource exposing name, email, company, and the plan / subscription status / trial end mirrored from the user's billing account (null when the user has no billing account).", "operationId": "309e3f57d75e31984a6c3e814b2fa5c5", "responses": { "200": { "description": "Authenticated user retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "users" }, "id": { "type": "string", "format": "uuid", "example": "9b1c1e2a-3f4d-4a5b-8c6d-7e8f9a0b1c2d" }, "attributes": { "properties": { "name": { "type": "string", "example": "Jane Doe" }, "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "company": { "type": "string", "example": "Acme Corp", "nullable": true }, "plan": { "type": "string", "example": "pro_monthly", "nullable": true }, "subscription_status": { "type": "string", "example": "active", "nullable": true }, "trial_ends_at": { "type": "string", "format": "date-time", "example": "2026-07-15T00:00:00+00:00", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] }, "delete": { "tags": [ "Authentication" ], "summary": "Delete the authenticated user's account and associated data (v1)", "description": "Irreversibly deletes the authenticated user's own account (issue #1979). Requires an interactive first-party session (a Passport personal access token is rejected with 401 at the authentication layer; an opaque `tc_` data key with 403 by the session gate) and an explicit confirmation body `{ \"data\": { \"confirm\": true } }`. Revokes the user's API keys and OAuth tokens, cancels the Stripe subscription, removes the Loops contact, then anonymizes the user's PII and soft-deletes the account. Billing/invoice financial records are retained (unlinked) per the documented retention policy.", "operationId": "e8a1bb03d625bcfb463a993c7db666a0", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "required": [ "data" ], "properties": { "data": { "required": [ "confirm" ], "properties": { "confirm": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Account deleted", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "users" }, "id": { "type": "string", "format": "uuid", "example": "9b1c1e2a-3f4d-4a5b-8c6d-7e8f9a0b1c2d" }, "attributes": { "properties": { "deleted": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated — no token, an invalid/expired token, or a Passport personal-access token (rejected outright at the auth layer since the opaque-key cutover)" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which authenticates fine on the data endpoints but may not delete its owner's account" }, "422": { "description": "Missing or invalid confirmation" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] }, "patch": { "tags": [ "Authentication" ], "summary": "Update the authenticated user's profile (v1)", "description": "Updates the authenticated user's own `name` and/or `company` from the portal Profile page. Authorized on the first-party interactive session (#1971): a long-lived data key (PAT / opaque `tc_` key) is rejected. The body is a JSON:API resource document (`data.type` = `users`); both attributes are optional, so a partial update leaves the omitted attribute unchanged, and `company` may be nulled to clear it. Requires `Content-Type: application/vnd.api+json` (415 otherwise). There is no user id in the path — the caller can only ever update their own record.", "operationId": "0f9a5f6c00ec84093c3e31174c0faf92", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "users" }, "attributes": { "properties": { "name": { "type": "string", "example": "Jane Doe" }, "company": { "type": "string", "example": "Acme Corp", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Profile updated; returns the same JSON:API user resource as GET /v1/me", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "users" }, "id": { "type": "string", "format": "uuid", "example": "9b1c1e2a-3f4d-4a5b-8c6d-7e8f9a0b1c2d" }, "attributes": { "properties": { "name": { "type": "string", "example": "Jane Doe" }, "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "company": { "type": "string", "example": "Acme Corp", "nullable": true }, "plan": { "type": "string", "example": "pro_monthly", "nullable": true }, "subscription_status": { "type": "string", "example": "active", "nullable": true }, "trial_ends_at": { "type": "string", "format": "date-time", "example": "2026-07-15T00:00:00+00:00", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthenticated — no token, an invalid/expired token, or a Passport personal-access token (rejected outright at the auth layer since the opaque-key cutover)" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which authenticates fine on the data endpoints but may not rewrite its owner's profile" }, "415": { "description": "Content-Type is not application/vnd.api+json" }, "422": { "description": "Validation failed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] } }, "/v1/object-attributes": { "get": { "tags": [ "ObjectAttributes v1" ], "summary": "Get all object attributes (v1)", "description": "Retrieve a paginated list of all object attributes (card-specific attribute instances)", "operationId": "fc7b19c2bcfe222f1f89908019f1e5fb", "parameters": [ { "name": "limit", "in": "query", "description": "Number of object attributes per page", "required": false, "schema": { "type": "integer", "example": 25, "default": 25 } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of object attributes retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectAttribute" } }, "included": { "type": "array", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "ObjectAttributes v1" ], "summary": "Create a new object attribute (v1)", "description": "Create a new object attribute instance linking an attribute to a specific object (card)", "operationId": "381b1817fa6c11a076b632fb08f782b8", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "object-attributes" }, "attributes": { "required": [ "attribute_id", "attribute_value", "object_type", "object_id" ], "properties": { "attribute_id": { "description": "ID of the attribute definition", "type": "string", "format": "uuid" }, "attribute_value": { "description": "Value of the attribute for this object", "type": "string", "example": "Authenticated" }, "object_type": { "description": "Type of object this attribute is attached to", "type": "string", "example": "App\\Models\\Card" }, "object_id": { "description": "ID of the object this attribute is attached to", "type": "string", "format": "uuid" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Object attribute created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ObjectAttribute" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/object-attributes/{id}": { "get": { "tags": [ "ObjectAttributes v1" ], "summary": "Get a specific object attribute (v1)", "description": "Retrieve detailed information about a specific object attribute by ID", "operationId": "732eebf73afde0f614385eb2f2723f48", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the object attribute to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Object attribute retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ObjectAttribute" }, "included": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Object attribute not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "ObjectAttributes v1" ], "summary": "Delete an object attribute (v1)", "description": "Delete an existing object attribute instance", "operationId": "a4d7e533a0f10965e57a0b9d3efbeea1", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the object attribute to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Object attribute deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Object attribute not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "ObjectAttributes v1" ], "summary": "Update an object attribute (v1)", "description": "Update an existing object attribute instance", "operationId": "fe9fc288abdc2b30b0c3525af2674601", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the object attribute to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "object-attributes" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "attribute_id": { "type": "string", "format": "uuid" }, "attribute_value": { "type": "string", "example": "Authenticated" }, "object_type": { "type": "string", "example": "App\\Models\\Card" }, "object_id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Object attribute updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ObjectAttribute" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Object attribute not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/user/password": { "patch": { "tags": [ "Authentication" ], "summary": "Change the authenticated user's password", "description": "Verifies the caller's current password, validates and rehashes the new one, and persists it. On success the user's OTHER OAuth access/refresh tokens are revoked (other login sessions and Passport personal-access tokens stop authenticating; opaque `tc_` data keys live in a separate store and are NOT revoked by this sweep) while the current session stays alive. Requires an interactive first-party session; long-lived data keys are rejected.", "operationId": "acc456f77f0764307b7b1c931db49230", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "user-passwords" }, "attributes": { "required": [ "current_password", "new_password", "new_password_confirmation" ], "properties": { "current_password": { "type": "string", "format": "password", "example": "current-secret" }, "new_password": { "type": "string", "format": "password", "example": "new-secret-123", "minLength": 8 }, "new_password_confirmation": { "type": "string", "format": "password", "example": "new-secret-123" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Password changed; other tokens revoked" }, "401": { "description": "Unauthenticated — no token, an invalid/expired token, or a Passport personal-access token (rejected outright at the auth layer since the opaque-key cutover)" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which authenticates fine on the data endpoints but may not change its owner's password" }, "422": { "description": "Wrong current password or new password fails the rules" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] } }, "/v1/players": { "get": { "tags": [ "Players v1" ], "summary": "Get all players (v1)", "description": "Retrieve a paginated list of all players with optional filtering", "operationId": "004e683e9cc71367abd00c0be1030180", "parameters": [ { "name": "first_name", "in": "query", "description": "Filter by player first name", "required": false, "schema": { "type": "string", "example": "Michael" } }, { "name": "last_name", "in": "query", "description": "Filter by player last name", "required": false, "schema": { "type": "string", "example": "Jordan" } }, { "name": "full_name", "in": "query", "description": "Filter by full name (searches both first and last name)", "required": false, "schema": { "type": "string", "example": "Michael Jordan" } }, { "name": "limit", "in": "query", "description": "Number of players per page (max 100, default 25)", "required": false, "schema": { "type": "integer", "example": 25, "default": 25, "maximum": 100 } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of players retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Player" } }, "included": { "type": "array", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidQueryParameter" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Players v1" ], "summary": "Create a new player (v1)", "description": "Create a new player record", "operationId": "f55914131a54823b5d9750edbfae138d", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "players" }, "attributes": { "properties": { "first_name": { "type": "string", "example": "Michael" }, "last_name": { "type": "string", "example": "Jordan" }, "position": { "type": "string", "example": "Shooting Guard", "nullable": true }, "full_name": { "description": "Alternative to first_name/last_name", "type": "string", "example": "Michael Jordan" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Player created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Player" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/players/{id}": { "get": { "tags": [ "Players v1" ], "summary": "Get a specific player (v1)", "description": "Retrieve detailed information about a specific player by ID", "operationId": "aec93dd485cc6c179e3a836a79844a16", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the player to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Player retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Player" }, "included": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Player not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Players v1" ], "summary": "Delete a player (v1)", "description": "Delete an existing player record", "operationId": "482616b1181bd0f6c767dd036c4105f4", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the player to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Player deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Player not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Players v1" ], "summary": "Update a player (v1)", "description": "Update an existing player record", "operationId": "d75d2155d9adb34c0cafa35706ddcc58", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the player to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "players" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "first_name": { "type": "string", "example": "Michael" }, "last_name": { "type": "string", "example": "Jordan" }, "position": { "type": "string", "example": "Shooting Guard", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Player updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Player" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Player not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/player-teams": { "get": { "tags": [ "PlayerTeams v1" ], "summary": "Get all player-team associations (v1)", "description": "Retrieve a paginated list of player-team associations with optional filtering", "operationId": "bac8098162a1769b7a643ff1107e6315", "parameters": [ { "name": "team_id", "in": "query", "description": "Filter by team ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "player_id", "in": "query", "description": "Filter by player ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of player-teams per page", "required": false, "schema": { "type": "integer", "example": 25, "default": 25 } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include (player,team)", "required": false, "schema": { "type": "string", "example": "player,team" } } ], "responses": { "200": { "description": "List of player-team associations retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PlayerTeam" } }, "included": { "type": "array", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "PlayerTeams v1" ], "summary": "Create a new player-team association (v1)", "description": "Create a new player-team association record", "operationId": "295b606baebd4c1ce51f877e14aa5d97", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "playerteams" }, "attributes": { "required": [ "player_id", "team_id" ], "properties": { "player_id": { "description": "ID of the player", "type": "string", "format": "uuid" }, "team_id": { "description": "ID of the team", "type": "string", "format": "uuid" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Player-team association created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PlayerTeam" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/player-teams/{id}": { "get": { "tags": [ "PlayerTeams v1" ], "summary": "Get a specific player-team association (v1)", "description": "Retrieve detailed information about a specific player-team association by ID", "operationId": "67b2b993082f43a8085d18f017ed85db", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the player-team association to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include (player,team)", "required": false, "schema": { "type": "string", "example": "player,team" } } ], "responses": { "200": { "description": "Player-team association retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PlayerTeam" }, "included": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Player-team association not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "PlayerTeams v1" ], "summary": "Delete a player-team association (v1)", "description": "Delete an existing player-team association record", "operationId": "c661c9c1e83b4b8840e29decd9b991f0", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the player-team association to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Player-team association deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Player-team association not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "PlayerTeams v1" ], "summary": "Update a player-team association (v1)", "description": "Update an existing player-team association record (PATCH only; PUT is not supported and returns 405 Method Not Allowed).", "operationId": "73cefbbd642ef28bd268d920830eecab", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the player-team association to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "playerteams" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "player_id": { "description": "ID of the player", "type": "string", "format": "uuid" }, "team_id": { "description": "ID of the team", "type": "string", "format": "uuid" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Player-team association updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/PlayerTeam" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Player-team association not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/sets": { "get": { "tags": [ "Sets v1" ], "summary": "Get all card sets (v1)", "description": "Retrieve a paginated list of all trading card sets", "operationId": "d7f2227fc3316148ca488a16c52a8395", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Number of sets per page (max 100, default 25)", "required": false, "schema": { "type": "integer", "example": 25, "default": 25, "maximum": 100 } }, { "name": "limit", "in": "query", "description": "Number of sets per page (deprecated, use per_page instead)", "required": false, "deprecated": true, "schema": { "type": "integer", "example": 25, "default": 25 } }, { "name": "order_by", "in": "query", "description": "Field to order by", "required": false, "schema": { "type": "string", "example": "name", "default": "name", "enum": [ "name", "created_at", "updated_at", "card_count" ] } }, { "name": "sort", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] } }, { "name": "name", "in": "query", "description": "Filter by set name. The value is an exact match by default. Prefix it with `like:` for a case-insensitive substring match (for example `like:2021 Topps`). Inside a `like:` value, `%` and `_` are matched literally rather than acting as SQL wildcards.", "required": false, "schema": { "type": "string", "example": "like:2021 Topps" } }, { "name": "genre", "in": "query", "description": "Filter by genre ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "year", "in": "query", "description": "Filter by year ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "brand", "in": "query", "description": "Filter by brand ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "manufacturer", "in": "query", "description": "Filter by manufacturer ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "parent_id", "in": "query", "description": "Filter by parent set ID (returns child sets/parallels of the specified parent)", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "scope", "in": "query", "description": "Row scope for the listing. `root` (the default) returns only sets without a parent, so parallels, inserts, autograph subsets and variations are omitted -- the default `meta.pagination.total` is therefore a count of root sets, not of the whole catalog. `all` returns every set. Ignored when `parent_id` is supplied, which always returns that parent's children. When `scope` is omitted a `name` query searches every set for backward compatibility; pass `scope=root` explicitly to keep a `name` search to root sets.", "required": false, "schema": { "type": "string", "example": "all", "enum": [ "root", "all" ] } }, { "name": "filter[status]", "in": "query", "description": "Filter by status (requires X-TCAPI-Ignore-Status header to see draft sets)", "required": false, "schema": { "type": "string", "enum": [ "published", "draft" ] } } ], "responses": { "200": { "description": "List of card sets retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Set" } }, "included": { "type": "array", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "properties": { "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "scope": { "$ref": "#/components/schemas/ListingScopeMeta" } }, "type": "object" } }, "type": "object" } } } }, "400": { "$ref": "#/components/responses/InvalidQueryParameter" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Sets v1" ], "summary": "Create a new set (v1)", "description": "Create a new trading card set", "operationId": "b5d29d875d5effb4b734eec7f256ea3f", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "sets" }, "attributes": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "1989 Topps Baseball" }, "description": { "type": "string", "nullable": true }, "total_cards": { "type": "integer", "example": 792, "nullable": true }, "genre_id": { "type": "string", "format": "uuid", "nullable": true }, "manufacturer_id": { "type": "string", "format": "uuid", "nullable": true }, "brand_id": { "type": "string", "format": "uuid", "nullable": true }, "year_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Set created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Set" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/sets/{id}": { "get": { "tags": [ "Sets v1" ], "summary": "Get a specific set (v1)", "description": "Retrieve detailed information about a specific trading card set by ID", "operationId": "064e89a4003497d86c7de37a88f2ed81", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the set to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Set retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Set" }, "included": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Sets v1" ], "summary": "Delete a set (v1)", "description": "Delete an existing trading card set. By default the deletion is refused with a 409 when the set is still published or still has child records (cards, set sources, subsets); the response names the specific blocker(s). Pass force=true to cascade-delete those children and remove the set in a single call.", "operationId": "68688782f14166f901b4aa291b6d5973", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the set to delete", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "description": "When true, cascade-delete remaining children (cards, set sources, subsets) and remove the set even if it is published. When false or omitted, a published set or a set with remaining children is refused with a structured 409.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "confirm", "in": "query", "description": "Reserved confirmation flag accepted for forward compatibility with the documented delete contract; parsed as a boolean and currently advisory.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "204": { "description": "Set deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set not found" }, "409": { "description": "Set deletion blocked — published or has remaining children and force was not set" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Sets v1" ], "summary": "Update a set (v1)", "description": "Update an existing trading card set", "operationId": "6bb0be294bfc0faf43f110f3ffae8d47", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the set to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "sets" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "1989 Topps Baseball" }, "description": { "type": "string", "nullable": true }, "total_cards": { "type": "integer", "example": 792, "nullable": true }, "genre_id": { "type": "string", "format": "uuid", "nullable": true }, "manufacturer_id": { "type": "string", "format": "uuid", "nullable": true }, "brand_id": { "type": "string", "format": "uuid", "nullable": true }, "year_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Set updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Set" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/sets/{set}/checklist": { "get": { "tags": [ "Sets v1" ], "summary": "Get set checklist (v1)", "description": "Retrieve the complete checklist for a trading card set including all cards. Supports compact format for large sets to avoid response size limits. Compact format returns only id, number, name, has_player, and has_team fields, reducing response size by ~75%.", "operationId": "82e0a344b3cb47b9442635557b96a45c", "parameters": [ { "name": "set", "in": "path", "description": "UUID of the set to get checklist for", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "description": "Response format: 'full' returns all card fields, 'compact' returns only id, number, name, has_player, and has_team", "required": false, "schema": { "type": "string", "example": "compact", "default": "full", "enum": [ "full", "compact" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination (starts at 1)", "required": false, "schema": { "type": "integer", "example": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of cards per page (max 100, returns all if not specified)", "required": false, "schema": { "type": "integer", "example": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Set checklist retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Set" }, "included": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Sets v1" ], "summary": "Add checklist to set (v1)", "description": "Add or import a checklist to a trading card set. Can either generate empty cards or parse a detailed checklist.", "operationId": "a78f313aeae29e0855599166c2acef1c", "parameters": [ { "name": "set", "in": "path", "description": "UUID of the set to add checklist to", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "queue", "in": "query", "description": "Queue the import for async processing. When omitted, large checklists (more than 50 lines) are auto-queued and smaller ones run synchronously. Pass queue=true to force async or queue=false to force sync.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "required": false, "content": { "application/vnd.api+json": { "schema": { "description": "Leave empty to generate empty cards based on total_cards, or provide checklist data to parse", "properties": { "data": { "properties": { "type": { "type": "string", "example": "checklist" }, "attributes": { "properties": { "lines": { "description": "Checklist lines to parse, one entry per line. Lines starting with '#' denote a section. More than 50 lines are auto-queued when the queue parameter is omitted.", "type": "array", "items": { "type": "string" }, "example": [ "# Base Set", "1 Mike Trout - Los Angeles Angels" ] } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "202": { "description": "Checklist processing accepted (async operation)" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Sets v1" ], "summary": "Delete set checklist (v1)", "description": "Bulk delete cards from a trading card set. Supports optional range filtering by card number. Without range parameters, all cards in the set are deleted.", "operationId": "31ad1d4b40f248e3de1257dc9439e302", "parameters": [ { "name": "set", "in": "path", "description": "UUID of the set to delete cards from", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from_number", "in": "query", "description": "Start of card number range to delete (inclusive, integer >= 1)", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "to_number", "in": "query", "description": "End of card number range to delete (inclusive, integer >= 1, must be >= from_number)", "required": false, "schema": { "type": "integer", "example": 100, "minimum": 1 } }, { "name": "queue", "in": "query", "description": "Queue the deletion for async processing (recommended for large sets)", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Cards deleted successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "bulk_delete_result" }, "attributes": { "properties": { "cards_deleted": { "type": "integer", "example": 50 }, "set_id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "202": { "description": "Deletion queued for async processing" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "403": { "description": "Forbidden - missing delete scope" }, "404": { "description": "Set not found" }, "422": { "description": "Validation error - invalid from_number or to_number" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/set-sources": { "get": { "tags": [ "Set Sources v1" ], "summary": "Get all set sources (v1)", "description": "Retrieve all set sources. Filter by set_id and/or source_type using filter[] params.", "operationId": "8e46b85ee745c5d94555cc8e169ff704", "parameters": [ { "name": "filter[set_id]", "in": "query", "description": "Filter by set UUID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[source_type]", "in": "query", "description": "Filter by source type", "required": false, "schema": { "type": "string", "enum": [ "checklist", "metadata", "images" ] } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include (set)", "required": false, "schema": { "type": "string", "example": "set" } }, { "name": "page", "in": "query", "description": "Page number for pagination", "required": false, "schema": { "type": "integer", "example": 1 } }, { "name": "per_page", "in": "query", "description": "Number of items per page (default 50, max 200)", "required": false, "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "List of set sources retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SetSource" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Set Sources v1" ], "summary": "Create a new set source (v1)", "description": "Create a new set source tracking record", "operationId": "308a40c6c9b8c1118daf5896f2e77f5f", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "set_sources" }, "attributes": { "required": [ "set_id", "source_url", "source_type" ], "properties": { "set_id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" }, "source_url": { "type": "string", "format": "url", "example": "https://example.com/checklist" }, "source_name": { "type": "string", "example": "CardboardConnection", "nullable": true }, "source_type": { "type": "string", "example": "checklist", "enum": [ "checklist", "metadata", "images" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Set source created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SetSource" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/set-sources/{id}": { "get": { "tags": [ "Set Sources v1" ], "summary": "Get a specific set source (v1)", "description": "Retrieve detailed information about a specific set source by ID", "operationId": "85bb8d9fce82173ef7cc0e7abc8291e7", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the set source to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include (set)", "required": false, "schema": { "type": "string", "example": "set" } } ], "responses": { "200": { "description": "Set source retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SetSource" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set source not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Set Sources v1" ], "summary": "Delete a set source (v1)", "description": "Delete an existing set source", "operationId": "d0e75e6b67e2aa265f997a698ad8dba7", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the set source to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Set source deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set source not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Set Sources v1" ], "summary": "Update a set source (v1)", "description": "Update an existing set source", "operationId": "dee25ab5f621e9bcb59d1a5f0780eed2", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the set source to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "set_sources" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "source_url": { "type": "string", "format": "url" }, "source_name": { "type": "string", "nullable": true }, "source_type": { "type": "string", "enum": [ "checklist", "metadata", "images" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Set source updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SetSource" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set source not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/internal/sets/{set}/todos": { "get": { "tags": [ "Internal" ], "summary": "List the workflow todos for a set (internal)", "description": "Returns the set's workflow todos ordered by sort_order. Returns an empty collection when the set exists but has no workflow initialized. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "f3e58bec46b822177fd4a30090d7e1b2", "parameters": [ { "name": "set", "in": "path", "description": "UUID of the parent set", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of set todos (empty when no workflow initialized)", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SetTodo" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "404": { "description": "Set not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer": [] } ], "x-internal": true }, "post": { "tags": [ "Internal" ], "summary": "Create a workflow todo for a set (internal)", "description": "Create a new workflow todo on the set's workflow. The todo is bound to the set's existing workflow; the set must already have one. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "c7eccfe57b911e3ce79bf57ce921c4f5", "parameters": [ { "name": "set", "in": "path", "description": "UUID of the parent set", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "set_todos" }, "attributes": { "required": [ "step", "status" ], "properties": { "step": { "type": "string", "example": "fetch", "enum": [ "discover_sources", "fetch", "parse", "populate", "validate", "cleanup", "publish", "audit" ] }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "in_progress", "completed", "skipped", "blocked", "review" ] }, "sort_order": { "type": "integer", "nullable": true }, "notes": { "type": "string", "nullable": true }, "completed_by": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object", "example": { "data": { "type": "set_todos", "attributes": { "step": "fetch", "status": "pending" } } } } } } }, "responses": { "201": { "description": "Todo created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SetTodo" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "404": { "description": "Set or workflow not found" }, "409": { "description": "A todo for this step already exists on the workflow (unique_workflow_step constraint)" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer": [] } ], "x-internal": true } }, "/internal/sets/{set}/todos/{todo}": { "get": { "tags": [ "Internal" ], "summary": "Get a single workflow todo for a set (internal)", "description": "Returns a single todo scoped to the parent set. A todo from a different set returns 404. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "255ac14345bff610c6c2060c90ed5247", "parameters": [ { "name": "set", "in": "path", "description": "UUID of the parent set", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "todo", "in": "path", "description": "UUID of the set todo", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Todo retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SetTodo" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "404": { "description": "Todo not found for this set" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer": [] } ], "x-internal": true }, "delete": { "tags": [ "Internal" ], "summary": "Delete a workflow todo for a set (internal)", "description": "Delete a todo scoped to the parent set. A todo from a different set returns 404. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "47f31cf9b96262aab980421a915322e6", "parameters": [ { "name": "set", "in": "path", "description": "UUID of the parent set", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "todo", "in": "path", "description": "UUID of the set todo to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Todo deleted successfully" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "404": { "description": "Todo not found for this set" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer": [] } ], "x-internal": true }, "patch": { "tags": [ "Internal" ], "summary": "Update a set todo step status (internal)", "description": "Transition a workflow step. Enrichment steps skip ordering; others need prior completion. The todo is scoped to the parent set; a todo from a different set returns 404. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "2119152a268c0af16e41e70e848f2d12", "parameters": [ { "name": "set", "in": "path", "description": "UUID of the parent set", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "todo", "in": "path", "description": "UUID of the set todo to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "set_todos" }, "attributes": { "required": [ "status" ], "properties": { "status": { "type": "string", "example": "in_progress", "enum": [ "pending", "in_progress", "completed", "skipped", "blocked", "review" ] }, "notes": { "type": "string", "nullable": true }, "completed_by": { "type": "string", "nullable": true }, "issues_found": { "type": "boolean", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object", "example": { "data": { "type": "set_todos", "attributes": { "status": "in_progress" } } } } } } }, "responses": { "200": { "description": "Todo updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SetTodo" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "404": { "description": "Todo not found for this set" }, "422": { "description": "Validation error or dependency not met" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer": [] } ], "x-internal": true } }, "/v1/signup": { "post": { "tags": [ "Authentication" ], "summary": "Self-service signup (v1)", "description": "Creates an unverified user and dispatches a verification email. Public (no authentication). Gated on remaining founding-pool capacity; when the pool is full a waitlist response is returned. The success response is identical whether or not the email already exists (non-enumerating).\n\n**Requires a valid invite code** (`data.attributes.invite_code`, issue #2282). A missing code is a 422 validation error; a code that is unknown, revoked, expired, or fully used is rejected with `invite_invalid`, `invite_expired` (410) or `invite_exhausted`. Holding an invite is permission to create an account — it does NOT reserve a founding slot, which is still claimed first-come-first-served at `POST /v1/signup/verify`. Use `POST /v1/invites/validate` to check a code without attempting a signup.\n\n**A re-submit never changes an existing account's password.** When the address already belongs to an account, the submitted password is discarded and the account keeps whatever credential it currently has. For an account that is still unverified the verification email is re-sent, so re-submitting is a valid way to recover a lost link — but the password sent with it does not take effect, and the account's existing password is unaffected. Overwriting it is deliberately not supported: this endpoint is unauthenticated and cannot prove the re-submitter started the signup, so allowing it would let an attacker plant a credential that the victim's own verification click activates. Prefer `POST /v1/signup/resend`, which recovers an expired link from the token alone and never asks for a password. Because the 202 body is byte-identical on every branch, its `meta.message` states this conditionally rather than only when it applies.", "operationId": "ff168ba7eef08e2d776b3129ac9e52eb", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "signups" }, "attributes": { "required": [ "email", "password", "invite_code" ], "properties": { "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "password": { "type": "string", "format": "password", "example": "correct horse battery" }, "invite_code": { "type": "string", "example": "FOUNDING-2026" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Founding pool full; waitlist response" }, "202": { "description": "Signup accepted; verification email dispatched. Byte-identical for a brand-new address, an existing unverified one (verification re-sent), and an existing verified one (nothing sent). `meta.message` carries the conditional caveat that this request does not change the password of an account that already existed." }, "410": { "description": "Invite code has expired" }, "422": { "description": "Validation error, or the invite code is unknown, revoked, or fully used" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/v1/signup/verify": { "post": { "tags": [ "Authentication" ], "summary": "Verify signup email, start trial, issue API key (v1)", "description": "Redeems the emailed verification token: marks the email verified, atomically claims a founding slot, starts a 14-day app-managed trial, issues the single opaque `tc_live_` API key (returned once), and sends the welcome email. Public (no authentication) — the token in the JSON:API body is the sole authorization. When the founding pool has filled since signup a waitlist response is returned and no trial is started.", "operationId": "fc737ec5bc5e8cd8a264b6f29389281f", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "email-verifications" }, "attributes": { "required": [ "token" ], "properties": { "token": { "type": "string", "example": "kQ8mZ3xR7vL2nP9wB4dF6sT1hJ0yC5gAeU3iO8qW2rY7tK4uM6bN1vX9zD5cH0f" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Email verified; trial started and API key issued (or a waitlist response when the pool is full, which also enrolls the token-proven address into the founding interest list so it receives the notification sent when more spots open; the waitlist branch leaves the email unverified and the token redeemable)" }, "410": { "description": "Verification token has expired" }, "422": { "description": "Verification token is missing, invalid, or already used" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/v1/signup/resend": { "post": { "tags": [ "Authentication" ], "summary": "Resend the signup verification email from an expired token (v1)", "description": "Mints a fresh verification token for the account the supplied token belongs to and re-sends the verification email. Public (no authentication) — the token in the JSON:API body is the sole authorization, which is what lets the marketing site's `/verify?token=…` page offer a one-click resend when `POST /v1/signup/verify` has answered 410 `token_expired`. An **expired** token is accepted here; that is the whole point of the endpoint.\n\n**Token rotation, not extension:** a successful resend replaces the stored token and its expiry, so the previous link stops working immediately and the new one carries a full 24-hour window. Because rotation is immediate, a spent token keeps replaying its 202 for 60 seconds — a double-submitted or retried request is idempotent and sends no second email, rather than reporting the link it just replaced as unknown.\n\nThe 202 response is identical whether or not the account is already verified (non-enumerating); the email is only dispatched when it is not. A token that resolves to no account — never issued, already rotated, or burned by a completed verification — is answered with 422 `token_unknown`, which is safe to distinguish because the token is a 64-character random secret rather than a guessable identifier. The token must be sent in the JSON body; a token in the query string is ignored, since a query string is recorded by proxies and travels onward in `Referer`. Unlike signup and verify, this endpoint is NOT gated on founding-pool capacity: capacity is enforced when the link is redeemed, and a waitlist response here would be indistinguishable from a sent email.\n\nThrottled by `throttle:signup-resend` per IP and per token, on top of the default `api` limit, because every accepted call sends an email — so a 429 here can arrive well before the general rate limit is spent.", "operationId": "e82aa954f8ab107629d53d2034bdeeb6", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "verification-resends" }, "attributes": { "required": [ "token" ], "properties": { "token": { "type": "string", "example": "kQ8mZ3xR7vL2nP9wB4dF6sT1hJ0yC5gAeU3iO8qW2rY7tK4uM6bN1vX9zD5cH0f" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "202": { "description": "Resend accepted; a new verification email was dispatched unless the account is already verified (identical response either way)" }, "422": { "description": "Verification token is missing, malformed, or resolves to no account" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/v1/stats/{type}": { "get": { "tags": [ "Statistics v1", "Internal" ], "summary": "Get statistics for a model type (v1)", "description": "Retrieve daily statistics showing creation and deletion counts for a specific model type. For the set-derived types (cards, sets) the series is filtered to the set statuses the caller's token may see; taxonomy types are ungated.", "operationId": "f3f6b9d8cbe9a644362d073b33c284f6", "parameters": [ { "name": "type", "in": "path", "description": "Type of model to get statistics for (e.g., cards, sets, players)", "required": true, "schema": { "type": "string", "example": "cards" } } ], "responses": { "200": { "description": "Statistics retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "stats" }, "attributes": { "properties": { "model": { "type": "string", "example": "cards" }, "unit": { "type": "string", "example": "daily" }, "count": { "type": "integer", "example": 30 }, "stats": { "type": "array", "items": { "properties": { "date": { "type": "string", "format": "date", "example": "2024-01-15" }, "count": { "type": "integer", "example": 5 }, "total": { "type": "integer", "example": 150 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Model type not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/stats/counts": { "get": { "tags": [ "Statistics v1" ], "summary": "Get current counts for all entity types", "description": "Get entity counts by status. Cached for 1 hour. Tokens without the internal, read:all-status or read:draft scope see a published-only view: total equals published and draft is 0.", "operationId": "f5ddbc369d67b2c50c26ed32422ce1e2", "responses": { "200": { "description": "Counts retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "stats" }, "attributes": { "properties": { "counts": { "type": "array", "items": { "properties": { "entity_type": { "type": "string", "example": "set" }, "total": { "type": "integer", "example": 21616 }, "published": { "type": "integer", "example": 730 }, "draft": { "type": "integer", "example": 20886 }, "archived": { "type": "integer", "example": 0 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/stats/snapshots": { "get": { "tags": [ "Statistics v1" ], "summary": "Get historical snapshots with optional filtering", "description": "Get historical snapshots with date/type filters. Tokens without the internal, read:all-status or read:draft scope see a published-only view: total equals published and draft is 0.", "operationId": "e333471f011adf35b885874732ead2e4", "parameters": [ { "name": "entity_type", "in": "query", "description": "Filter by entity type", "required": false, "schema": { "type": "string", "enum": [ "set", "card", "player", "team" ] } }, { "name": "from", "in": "query", "description": "Filter snapshots from this date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "to", "in": "query", "description": "Filter snapshots to this date (YYYY-MM-DD)", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, { "name": "per_page", "in": "query", "description": "Number of results per page (default: 100, max: 500)", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Snapshots retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "snapshots" }, "attributes": { "properties": { "snapshots": { "type": "array", "items": { "properties": { "date": { "type": "string", "format": "date", "example": "2024-01-15" }, "entity_type": { "type": "string", "example": "set" }, "total": { "type": "integer", "example": 21616 }, "published": { "type": "integer", "example": 730 }, "draft": { "type": "integer", "example": 20886 }, "archived": { "type": "integer", "example": 0 } }, "type": "object" } }, "entity_type": { "type": "string", "example": "set", "nullable": true }, "from": { "type": "string", "format": "date", "nullable": true }, "to": { "type": "string", "format": "date", "nullable": true } }, "type": "object" } }, "type": "object" }, "meta": { "properties": { "total": { "type": "integer", "example": 100 }, "per_page": { "type": "integer", "example": 100 }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/stats/growth": { "get": { "tags": [ "Statistics v1" ], "summary": "Get growth metrics for a specific time period", "description": "Compare current counts to previous period. Cached for 1 hour. Tokens without the internal, read:all-status or read:draft scope get metrics derived from published counts rather than totals.", "operationId": "f285ec768e8e87460ea8ce956e552910", "parameters": [ { "name": "period", "in": "query", "description": "Time period for comparison", "required": false, "schema": { "type": "string", "default": "7d", "enum": [ "7d", "30d", "90d", "1y", "week", "month" ] } } ], "responses": { "200": { "description": "Growth metrics retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "growth" }, "attributes": { "properties": { "period": { "type": "string", "example": "7d" }, "metrics": { "type": "array", "items": { "properties": { "entity_type": { "type": "string", "example": "set" }, "current": { "type": "integer", "example": 21616 }, "previous": { "type": "integer", "example": 21500 }, "change": { "type": "integer", "example": 116 }, "percentage_change": { "type": "number", "format": "float", "example": 0.54 } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/user/subscription": { "get": { "tags": [ "Authentication" ], "summary": "Get the authenticated user's subscription/plan and trial state", "description": "Returns the authenticated end user's plan, subscription status, trial state, and period/cancellation flags as a JSON:API resource. Read-only; never mutates billing state. A user with no billing account gets a graceful \"no plan\" resource (200), not a 500.", "operationId": "a80e5fe1cf791c06c3cb59e91a47bcc2", "responses": { "200": { "description": "Subscription/plan and trial state (null attributes when no billing account)" }, "401": { "description": "Unauthenticated — no token, an invalid/expired token, or a Passport personal-access token (rejected outright at the auth layer since the opaque-key cutover)" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which authenticates fine on the data endpoints but may not read its owner's subscription" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] } }, "/v1/sets/{id}/actions/sync-parallel": { "post": { "tags": [ "Sets v1" ], "summary": "Sync parallel set with parent (v1)", "description": "Add missing cards from parent set to a parallel set. This endpoint finds cards in the parent set that don't exist in the parallel set and creates them with their on-card relationships and attributes. This is the canonical JSON:API action-namespace route; the legacy `POST /v1/sets/{id}/sync-parallel` path is a deprecated alias.", "operationId": "f4725015825c1ecdd8439d3e750ee93e", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the parallel set to sync", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "queue", "in": "query", "description": "Queue the sync for async processing. Defaults to \"auto\", which forces queued processing when the parent set has more than 20 cards and otherwise runs the sync inline. Pass \"true\" to always queue or \"false\" to always run inline.", "required": false, "schema": { "type": "string", "default": "auto", "enum": [ "auto", "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "sync_parallel" }, "attributes": { "description": "No attributes currently required. Reserved for future options.", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Sync completed successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "sync_result" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "cards_created": { "type": "integer", "example": 15 }, "cards_updated": { "type": "integer", "example": 0 }, "cards_skipped": { "type": "integer", "example": 85 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "202": { "description": "Sync queued for async processing" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set not found" }, "422": { "description": "Invalid operation (set is not a parallel set or has no parent)" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/sets/{id}/sync-parallel": { "post": { "tags": [ "Sets v1" ], "summary": "Sync parallel set with parent (v1) — DEPRECATED alias", "description": "Deprecated RPC-style alias of `POST /v1/sets/{id}/actions/sync-parallel`. Behaves identically but responds with deprecation headers (`Deprecation`, `Sunset`, `Link`, `Warning`). Retained for a removal window; migrate to the action-namespace route. (issue #1500)", "operationId": "17cfeadf4d9671fc06943ad6c547563c", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the parallel set to sync", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "queue", "in": "query", "description": "Queue the sync for async processing. Defaults to \"auto\", which forces queued processing when the parent set has more than 20 cards and otherwise runs the sync inline. Pass \"true\" to always queue or \"false\" to always run inline.", "required": false, "schema": { "type": "string", "default": "auto", "enum": [ "auto", "true", "false" ] } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "sync_parallel" }, "attributes": { "description": "No attributes currently required. Reserved for future options.", "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Sync completed successfully. Includes deprecation headers (Deprecation/Sunset/Link/Warning).", "headers": { "Deprecation": { "description": "RFC 9745 deprecation timestamp (`@`).", "schema": { "type": "string", "example": "@1798761599" } }, "Sunset": { "description": "RFC 8594 sunset date (IMF-fixdate) for the planned v2 removal.", "schema": { "type": "string", "example": "Thu, 31 Dec 2026 23:59:59 GMT" } }, "Link": { "description": "Successor URL for the canonical action-namespace route.", "schema": { "type": "string", "example": "; rel=\"successor-version\"" } }, "Warning": { "description": "Human-readable migration note (RFC 7234 warn-code 299).", "schema": { "type": "string", "example": "299 - \"This API endpoint is deprecated and will be removed in v2. Please migrate to /v1/sets/{id}/actions/sync-parallel\"" } } }, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "sync_result" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "cards_created": { "type": "integer", "example": 15 }, "cards_updated": { "type": "integer", "example": 0 }, "cards_skipped": { "type": "integer", "example": 85 } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "202": { "description": "Sync queued for async processing. Includes the same deprecation headers as the 200 response.", "headers": { "Deprecation": { "description": "RFC 9745 deprecation timestamp (`@`).", "schema": { "type": "string", "example": "@1798761599" } }, "Sunset": { "description": "RFC 8594 sunset date (IMF-fixdate) for the planned v2 removal.", "schema": { "type": "string", "example": "Thu, 31 Dec 2026 23:59:59 GMT" } }, "Link": { "description": "Successor URL for the canonical action-namespace route.", "schema": { "type": "string", "example": "; rel=\"successor-version\"" } }, "Warning": { "description": "Human-readable migration note (RFC 7234 warn-code 299).", "schema": { "type": "string", "example": "299 - \"This API endpoint is deprecated and will be removed in v2. Please migrate to /v1/sets/{id}/actions/sync-parallel\"" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set not found" }, "422": { "description": "Invalid operation (set is not a parallel set or has no parent)" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "deprecated": true } }, "/v1/teams": { "get": { "tags": [ "Teams v1" ], "summary": "Get all teams (v1)", "description": "Retrieve a paginated list of all teams with optional filtering", "operationId": "f374ab65aad02e4bfaeead9792081430", "parameters": [ { "name": "location", "in": "query", "description": "Filter by team location", "required": false, "schema": { "type": "string", "example": "Chicago" } }, { "name": "mascot", "in": "query", "description": "Filter by team mascot", "required": false, "schema": { "type": "string", "example": "Bulls" } }, { "name": "name", "in": "query", "description": "Filter by full team name (searches both location and mascot)", "required": false, "schema": { "type": "string", "example": "Chicago Bulls" } }, { "name": "genre_id", "in": "query", "description": "Filter by genre ID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Number of teams per page (max 100, default 25)", "required": false, "schema": { "type": "integer", "example": 25, "default": 25, "maximum": 100 } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of teams retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } }, "included": { "type": "array", "items": { "type": "object" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "400": { "description": "Invalid pagination parameter (limit exceeds the maximum of 100)" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Teams v1" ], "summary": "Create a new team (v1)", "description": "Create a new team record", "operationId": "b900abe08fcefd441f052fe85860f6ac", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "teams" }, "attributes": { "properties": { "location": { "type": "string", "example": "Chicago" }, "mascot": { "type": "string", "example": "Bulls" }, "city": { "type": "string", "example": "Chicago", "nullable": true }, "abbreviation": { "type": "string", "example": "CHI", "nullable": true }, "name": { "description": "Alternative to location/mascot", "type": "string", "example": "Chicago Bulls" }, "genre_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Team created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Team" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/teams/{id}": { "get": { "tags": [ "Teams v1" ], "summary": "Get a specific team (v1)", "description": "Retrieve detailed information about a specific team by ID", "operationId": "8a0d7c91b4690ce9461178c3116825b7", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the team to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Team" }, "included": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Team not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Teams v1" ], "summary": "Delete a team (v1)", "description": "Delete an existing team record", "operationId": "af63613177386e048b8490a28d3347fe", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the team to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Team deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Team not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Teams v1" ], "summary": "Update a team (v1)", "description": "Update an existing team record", "operationId": "645f813ae58b9bae05f3b24b37a65f27", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the team to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "teams" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "location": { "type": "string", "example": "Chicago" }, "mascot": { "type": "string", "example": "Bulls" }, "city": { "type": "string", "example": "Chicago", "nullable": true }, "abbreviation": { "type": "string", "example": "CHI", "nullable": true }, "genre_id": { "type": "string", "format": "uuid", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Team updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Team" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Team not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/user/usage": { "get": { "tags": [ "Authentication" ], "summary": "Get the authenticated caller's current rate-limit window", "description": "Returns the live rate-limit window (limit, remaining, resets_at) for the authenticated user's `tc_live_` API key, as a JSON:API resource. **Both credential types work:** an opaque `tc_live_` API key may read its own usage, and so may an interactive first-party portal session — unlike the sibling account-management endpoints (`GET/POST/DELETE /v1/user/api-key`, `PATCH /v1/user/email`), which reject a data key with 403. Whichever credential calls it, the window reported is always the authenticated user's own API-key bucket, deliberately NOT the bucket of the token making this request, since the portal proxies its screens with an interactive session token whose browsing would otherwise be reported as API usage (issue #2304). **The call is not metered:** this endpoint is exempt from the `api` rate limiter it reports on, so polling your own usage never consumes the quota being reported (it has its own separate, more permissive limiter, hence the 429 below). A user with no API key is reported as a full, untouched window at their default tier. Read-only. The portal dashboard derives requests-used as `limit - remaining`.", "operationId": "1bde21c39c826e29ee96a49188f29535", "responses": { "200": { "description": "Current rate-limit window (limit, remaining, resets_at)" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Authenticated as an OAuth client rather than a user, so there is no usage window to report (machine-to-machine client-credentials token)" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] } }, "/v1/user/email": { "patch": { "tags": [ "Authentication" ], "summary": "Initiate a change of the authenticated user's login email", "description": "Validates a new login-email address (well-formed, unused, and different from the current login), stores it as a pending change, and emails a confirmation link to the NEW address. The login email is NOT changed until the confirmation link is redeemed via POST /v1/user/email/confirm. Authorized on an interactive first-party session (#1971); personal-access / opaque data keys are rejected.", "operationId": "21ecb42d39ea2583a24b34a5287b1243", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "user-emails" }, "attributes": { "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "new.address@example.com" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "202": { "description": "Change initiated; confirmation email dispatched to the new address" }, "401": { "description": "Unauthenticated — no token, an invalid/expired token, or a Passport personal-access token (rejected outright at the auth layer since the opaque-key cutover)" }, "403": { "description": "Authenticated but not an interactive first-party session — e.g. an opaque `tc_` data key, which authenticates fine on the data endpoints but may not change its owner's login email" }, "422": { "description": "Validation error (invalid, in-use, or unchanged address)" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ] } }, "/v1/user/email/confirm": { "post": { "tags": [ "Authentication" ], "summary": "Confirm a pending login-email change", "description": "Redeems the confirmation token emailed to the new address, promotes the pending address to the login email, and marks it verified. The previous address stops authenticating. Followed from an emailed link, so it authenticates on the opaque token alone (no session, no bearer). Rejects a missing, unknown, or expired token.", "operationId": "4e5a14a3899a58f546a69d2fb6f0ba9e", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "user-email-confirmations" }, "attributes": { "required": [ "token" ], "properties": { "token": { "type": "string" } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Login email changed and marked verified" }, "422": { "description": "Missing, unknown, or expired confirmation token" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [] } }, "/internal/sets/{set}/workflow": { "get": { "tags": [ "Internal" ], "summary": "Get the workflow state for a set (internal)", "description": "Returns the workflow record and its todos for the given set. Returns `{\"workflow\": null}` (200) when the set exists but has no workflow initialized. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "59df190c29d79e319d4a78f661e2d2b0", "parameters": [ { "name": "set", "in": "path", "description": "Set UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workflow state (null when not yet initialized)", "content": { "application/vnd.api+json": { "schema": { "properties": { "workflow": { "properties": { "id": { "type": "string", "format": "uuid" }, "set_id": { "type": "string", "format": "uuid" }, "priority": { "type": "integer" }, "current_step": { "type": "string", "nullable": true }, "todos": { "type": "array", "items": { "properties": { "id": { "type": "string", "format": "uuid" }, "step": { "type": "string" }, "status": { "type": "string" }, "sort_order": { "type": "integer" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "notes": { "description": "Free-form notes; reason text when status=review.", "type": "string", "nullable": true } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object", "nullable": true } }, "type": "object" }, "examples": { "initialized": { "summary": "Set with an initialized workflow and todos", "value": { "workflow": { "id": "550e8400-e29b-41d4-a716-446655440000", "set_id": "661f9511-f30c-52e5-b827-557766551111", "priority": 1, "current_step": "fetch", "todos": [ { "id": "772a0622-a41d-43f6-c938-668877662222", "step": "discover_sources", "status": "completed", "sort_order": 1, "started_at": "2024-03-15T09:00:00+00:00", "completed_at": "2024-03-15T09:15:00+00:00", "notes": null }, { "id": "883b1733-b52e-44a7-d049-779988773333", "step": "fetch", "status": "in_progress", "sort_order": 2, "started_at": "2024-03-15T09:20:00+00:00", "completed_at": null, "notes": "Retrying after transient 502 from source." } ], "created_at": "2024-03-15T08:00:00+00:00", "updated_at": "2024-03-15T10:30:00+00:00" } } }, "null": { "summary": "Set exists but workflow has not been initialized", "value": { "workflow": null } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "404": { "description": "Set not found" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ], "x-internal": true } }, "/internal/actionable-sets": { "get": { "tags": [ "Internal" ], "summary": "Get sets that are actionable for a given workflow step (internal)", "description": "Returns sets where the given step matches the requested status (default: pending). For pipeline steps with pending status, all prior steps must be completed or skipped. Enrichment steps bypass this requirement. Use status=review to find sets needing human intervention. Each row includes the current todo_id (for PATCH operations) and notes (the review reason when status=review). Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "997bebfad9d90fbc98aff8d52fb88c90", "parameters": [ { "name": "step", "in": "query", "description": "Workflow step (discover_sources, fetch, parse, populate, validate, cleanup, publish, audit)", "required": true, "schema": { "type": "string", "enum": [ "discover_sources", "fetch", "parse", "populate", "validate", "cleanup", "publish", "audit" ] } }, { "name": "status", "in": "query", "description": "Filter by todo status (default: pending). Use 'review' to find sets needing human intervention.", "required": false, "schema": { "type": "string", "default": "pending", "enum": [ "pending", "in_progress", "completed", "skipped", "blocked", "review" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return (1–100, default 25)", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } }, { "name": "priority", "in": "query", "description": "Priority filter: 'current' (current year), 'backlog' (prior years), or 'all' (default)", "required": false, "schema": { "type": "string", "enum": [ "current", "backlog", "all" ] } }, { "name": "genre_id", "in": "query", "description": "Filter by genre UUID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "year", "in": "query", "description": "Filter by year name (e.g. '2025', '2025-26')", "required": false, "schema": { "type": "string", "maxLength": 20 } } ], "responses": { "200": { "description": "List of actionable sets for the given step", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "todo_id": { "description": "ID of the current set_todo row. Use this to PATCH the todo (e.g. review→pending/skipped).", "type": "string", "format": "uuid" }, "set_id": { "type": "string", "format": "uuid" }, "set_name": { "type": "string" }, "genre": { "type": "string", "nullable": true }, "year": { "type": "string", "nullable": true }, "step": { "type": "string" }, "priority": { "type": "integer" }, "card_count": { "type": "integer" }, "has_sources": { "type": "boolean" }, "notes": { "description": "Free-form notes on the current todo. For status=review this is the reason the daemon flagged the step.", "type": "string", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "example": "2025-01-15T13:45:30+00:00" } }, "type": "object" } }, "meta": { "properties": { "total": { "type": "integer" }, "full_total": { "description": "Unpaginated count of rows matching the active filters (vs `total`, which is the size of the returned page).", "type": "integer" }, "step": { "type": "string" }, "status": { "type": "string" }, "priority_filter": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" }, "503": { "description": "Service unavailable — query timed out" } }, "security": [ { "bearer": [] } ], "x-internal": true } }, "/internal/actionable-sets/count": { "get": { "tags": [ "Internal" ], "summary": "Count sets that are actionable for a given workflow step (internal)", "description": "Returns the unpaginated count of sets that are actionable for the given step, using the exact same filters as GET /internal/actionable-sets (step, status, priority, genre_id, year) but without materializing the row page or the per-row card_count / has_sources subqueries. The returned count is consistent with that endpoint's full_total for identical filters. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "ee2aec66169cc9f39a82da071c2826bd", "parameters": [ { "name": "step", "in": "query", "description": "Workflow step (discover_sources, fetch, parse, populate, validate, cleanup, publish, audit)", "required": true, "schema": { "type": "string", "enum": [ "discover_sources", "fetch", "parse", "populate", "validate", "cleanup", "publish", "audit" ] } }, { "name": "status", "in": "query", "description": "Filter by todo status (default: pending). Use 'review' to find sets needing human intervention.", "required": false, "schema": { "type": "string", "default": "pending", "enum": [ "pending", "in_progress", "completed", "skipped", "blocked", "review" ] } }, { "name": "priority", "in": "query", "description": "Priority filter: 'current' (current year), 'backlog' (prior years), or 'all' (default)", "required": false, "schema": { "type": "string", "enum": [ "current", "backlog", "all" ] } }, { "name": "genre_id", "in": "query", "description": "Filter by genre UUID", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "year", "in": "query", "description": "Filter by year name (e.g. '2025', '2025-26')", "required": false, "schema": { "type": "string", "maxLength": 20 } }, { "name": "limit", "in": "query", "description": "Accepted for request-shape parity with GET /internal/actionable-sets but ignored: this endpoint returns an unpaginated count, so no row cap applies. Still validated (integer, 1-100) — an out-of-range value yields 422.", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Unpaginated count of actionable sets for the given step", "content": { "application/vnd.api+json": { "schema": { "properties": { "count": { "description": "Unpaginated count of sets matching the active filters. Equals GET /internal/actionable-sets full_total for identical filters.", "type": "integer" }, "meta": { "properties": { "step": { "type": "string" }, "status": { "type": "string" }, "priority_filter": { "type": "string" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" }, "503": { "description": "Service unavailable — query timed out" } }, "security": [ { "bearer": [] } ], "x-internal": true } }, "/internal/todo-initialization-jobs": { "post": { "tags": [ "Internal" ], "summary": "Bulk-initialize workflow todos for pre-existing sets (internal)", "description": "Initializes workflow todos for sets that have no existing workflow. Sets with existing workflows or published status are counted as skipped. When more than 100 sets would be processed, the operation is dispatched as a background job. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "81acfbe196184c07aca0b54fea5216a4", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "set_ids": { "description": "Specific set UUIDs to initialize. Mutually exclusive with all_draft.", "type": "array", "items": { "type": "string", "format": "uuid" } }, "all_draft": { "description": "Initialize all draft sets without existing workflows.", "type": "boolean" }, "genre_id": { "description": "Filter by genre (only valid with all_draft).", "type": "string", "format": "uuid" }, "year": { "description": "Filter by year name, e.g. '2025' (only valid with all_draft).", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Synchronous initialization result (≤ 100 sets)", "content": { "application/vnd.api+json": { "schema": { "properties": { "initialized": { "description": "Number of sets successfully initialized", "type": "integer" }, "skipped": { "description": "Number of sets skipped (already initialized or published)", "type": "integer" }, "errors": { "description": "Per-set errors encountered during processing", "type": "array", "items": { "type": "object" } }, "job_id": { "description": "Always null for synchronous processing", "type": "string", "nullable": true }, "resolved_count": { "description": "Number of set IDs resolved before processing", "type": "integer" }, "meta": { "description": "Diagnostic counts; null unless all_draft is true", "properties": { "total_draft_sets": { "description": "Total draft sets matching filters", "type": "integer" }, "draft_with_workflow": { "description": "Draft sets that already have workflows", "type": "integer" }, "draft_without_workflow": { "description": "Draft sets eligible for initialization", "type": "integer" } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "202": { "description": "Accepted — job dispatched asynchronously (> 100 sets). Poll GET /internal/todo-initialization-jobs/{job_id} for status.", "content": { "application/vnd.api+json": { "schema": { "properties": { "initialized": { "type": "integer", "example": 0 }, "skipped": { "type": "integer", "example": 0 }, "errors": { "type": "array", "items": { "type": "object" } }, "job_id": { "description": "Use this ID to poll the status endpoint", "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "pending" }, "resolved_count": { "description": "Number of set IDs resolved before dispatching", "type": "integer" }, "meta": { "description": "Diagnostic counts; null unless all_draft is true", "properties": { "total_draft_sets": { "description": "Total draft sets matching filters", "type": "integer" }, "draft_with_workflow": { "description": "Draft sets that already have workflows", "type": "integer" }, "draft_without_workflow": { "description": "Draft sets eligible for initialization", "type": "integer" } }, "type": "object", "nullable": true } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "security": [ { "bearer": [] } ], "x-internal": true } }, "/internal/todo-initialization-jobs/{job_id}": { "get": { "tags": [ "Internal" ], "summary": "Poll the status of an async bulk-initialize job (internal)", "description": "Returns the current status of a background bulk-initialize job. The job_id is obtained from the 202 response of POST /internal/todo-initialization-jobs. Results are retained for 24 hours after job completion. Internal endpoint: requires the `internal` OAuth scope (#1557).", "operationId": "180f3943c824315cd2794eeda2c6fdd6", "parameters": [ { "name": "job_id", "in": "path", "description": "Job UUID returned by the async bulk-initialize request", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job status (pending or completed)", "content": { "application/vnd.api+json": { "schema": { "properties": { "status": { "type": "string", "enum": [ "pending", "completed" ] }, "job_id": { "type": "string", "format": "uuid" }, "initialized": { "type": "integer", "nullable": true }, "skipped": { "type": "integer", "nullable": true }, "errors": { "type": "array", "items": { "type": "object" }, "nullable": true }, "resolved_count": { "description": "Number of set IDs resolved before processing", "type": "integer", "nullable": true }, "meta": { "description": "Diagnostic counts; null unless all_draft was used", "type": "object", "nullable": true } }, "type": "object", "example": { "status": "completed", "job_id": "550e8400-e29b-41d4-a716-446655440000", "initialized": 42, "skipped": 3, "errors": [], "resolved_count": 45, "meta": null } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - missing the internal scope" }, "404": { "description": "Job not found or expired" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearer": [] } ], "x-internal": true } }, "/v1/years": { "get": { "tags": [ "Years v1" ], "summary": "Get all years (v1)", "description": "Retrieve a list of all years available for trading card sets", "operationId": "f1bb799712a5a7a2bf5d85fee99fb4c0", "parameters": [ { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of years retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Year" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "Years v1" ], "summary": "Create a new year (v1)", "description": "Create a new year record for trading card classification", "operationId": "950f79c472b21da8a67c2742ca34fc7e", "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "years" }, "attributes": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "1989" }, "description": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "201": { "description": "Year created successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Year" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v1/years/{id}": { "get": { "tags": [ "Years v1" ], "summary": "Get a specific year (v1)", "description": "Retrieve detailed information about a specific year by ID", "operationId": "6397f74c26e9a18fbb3bd0e6aaad431b", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the year to retrieve", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Year retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Year" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Year not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "delete": { "tags": [ "Years v1" ], "summary": "Delete a year (v1)", "description": "Delete an existing year record", "operationId": "c8b33062a0150e328b5abd21d0ad22f9", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the year to delete", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Year deleted successfully" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Year not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } }, "patch": { "tags": [ "Years v1" ], "summary": "Update a year (v1)", "description": "Update an existing year record", "operationId": "be7ce854c317a27daea9f21af44bf34c", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the year to update", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "years" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "1989" }, "description": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Year updated successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Year" } }, "type": "object" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Year not found" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/v2/sets/{set}/checklist": { "get": { "tags": [ "Sets v2" ], "summary": "Get set checklist (v2)", "description": "Retrieve the complete checklist for a trading card set. V2 returns cards as the primary data with set information in the included array. Supports compact format for large sets to avoid response size limits. Compact format returns only id, number, name, has_player and has_team fields, reducing response size by ~75%. Compact also drops the JSON:API envelope: the response omits `included`, per-card `relationships`, and per-resource `links`. Top-level pagination `links` and `meta` are retained. An explicit `include` parameter is still honored on a compact request and re-adds the corresponding `included` and `relationships` members.", "operationId": "2fb6509dd34fbf8fe0054e0a0d24489e", "parameters": [ { "name": "set", "in": "path", "description": "UUID of the set to get checklist for", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include", "in": "query", "description": "Comma-separated list of relationships to include (set,oncard,attributes). Defaults to `set` under the full format and to none under `format=compact`; see the `format` parameter. Passing this parameter explicitly overrides the default in both formats.", "required": false, "schema": { "type": "string", "example": "set" } }, { "name": "format", "in": "query", "description": "Response format: 'full' returns all card fields, 'compact' returns only id, number, name, has_player and has_team. Compact additionally omits `included`, per-card `relationships`, and per-resource `links`; top-level pagination `links` and `meta` are retained. Pass an explicit `include` to re-add the corresponding envelope members.", "required": false, "schema": { "type": "string", "example": "compact", "default": "full", "enum": [ "full", "compact" ] } }, { "name": "page", "in": "query", "description": "Page number for pagination (starts at 1)", "required": false, "schema": { "type": "integer", "example": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of cards per page (max 100, returns all if not specified)", "required": false, "schema": { "type": "integer", "example": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Set checklist retrieved successfully", "content": { "application/vnd.api+json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "included": { "type": "array", "items": { "$ref": "#/components/schemas/Set" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" }, "402": { "$ref": "#/components/responses/SubscriptionRequired" }, "404": { "description": "Set not found" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } } } }, "/version": { "get": { "tags": [ "Version" ], "summary": "Get API version information", "description": "Retrieve version information about the API, application, and supported versions", "operationId": "68ebbc03a53fc2b59a83dae7499e4f64", "responses": { "200": { "description": "Version information retrieved successfully", "content": { "application/json": { "schema": { "properties": { "api_version": { "description": "Current API version", "type": "string", "example": "1.0" }, "app_version": { "description": "Application version", "type": "string", "example": "2.1.3" }, "build_date": { "description": "Build date", "type": "string", "example": "2024-01-15", "nullable": true }, "build_commit": { "description": "Git commit hash", "type": "string", "example": "abc123def", "nullable": true }, "supported_versions": { "description": "List of supported API versions", "type": "array", "items": { "type": "string" }, "example": [ "1.0", "1.1" ] }, "deprecated_versions": { "description": "List of deprecated API versions", "type": "array", "items": { "type": "string" }, "example": [ "0.9" ] }, "changelog_url": { "description": "URL to changelog", "type": "string", "example": "https://api.example.com/changelog", "nullable": true } }, "type": "object" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "description": "Internal server error" } }, "security": [] } } }, "components": { "schemas": { "Card": { "title": "Trading Card", "description": "A trading card resource following JSON:API specification", "properties": { "type": { "description": "Resource type", "type": "string", "example": "cards" }, "id": { "description": "Unique identifier", "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "attributes": { "properties": { "name": { "description": "Auto-generated card name", "type": "string", "example": "Michael Jordan" }, "number": { "description": "Card number within the set", "type": "string", "example": "23" }, "serial_number": { "description": "Serial number for limited cards", "type": "string", "example": "001/100", "nullable": true }, "image_uuid": { "description": "UUID reference for card image", "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "nullable": true }, "title": { "description": "Special title or designation", "type": "string", "example": "Rookie Card", "nullable": true }, "notes": { "description": "Additional notes about the card", "type": "string", "nullable": true }, "has_player": { "description": "True if the card has an associated player or player/team. Always present on card responses; computed in bulk only by the set checklist endpoint. On other endpoints the flag is not computed and defaults to false, so outside the set checklist endpoint a value of false means \"not computed\" rather than \"no player relationship\" — do not rely on it being authoritative there.", "type": "boolean", "example": true }, "has_team": { "description": "True if the card has an associated team or player/team. Always present on card responses; computed in bulk only by the set checklist endpoint. On other endpoints the flag is not computed and defaults to false, so outside the set checklist endpoint a value of false means \"not computed\" rather than \"no team relationship\" — do not rely on it being authoritative there.", "type": "boolean", "example": true }, "created_at": { "description": "Creation timestamp", "type": "string", "format": "date-time" }, "updated_at": { "description": "Last update timestamp", "type": "string", "format": "date-time" }, "url": { "description": "API URL for this card resource", "type": "string", "format": "uri" } }, "type": "object" }, "relationships": { "properties": { "set": { "properties": { "data": { "properties": { "type": { "type": "string", "example": "sets" }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } }, "type": "object" }, "oncard": { "properties": { "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "enum": [ "players", "teams", "playerteams" ] }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" }, "attributes": { "properties": { "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "example": "attributes" }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" }, "images": { "properties": { "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "example": "card_images" }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "Set": { "title": "Card Set", "description": "A trading card set resource", "properties": { "type": { "type": "string", "example": "sets" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "1989 Topps Baseball" }, "title": { "type": "string", "example": "Series 1", "nullable": true }, "description": { "type": "string", "nullable": true }, "card_count": { "type": "integer", "example": 792, "nullable": true }, "current_card_count": { "type": "integer", "example": 792 }, "is_parallel": { "type": "boolean", "example": false }, "is_insert": { "type": "boolean", "example": false }, "is_autograph": { "type": "boolean", "example": false }, "is_relic": { "type": "boolean", "example": false }, "is_variation": { "description": "Indicates a variation set with same card numbering but different visual treatment", "type": "boolean", "example": false }, "serial": { "type": "integer", "example": 250, "nullable": true }, "number_prefix": { "type": "string", "nullable": true }, "parent_set": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" }, "relationships": { "description": "Related resources. The genre, manufacturer, brand, and year relationships replace the previously flat FK attributes and are only populated when explicitly requested via ?include=genre,manufacturer,brand,year.", "properties": { "sources": { "properties": { "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "example": "set_sources" }, "id": { "type": "string", "format": "uuid" } }, "type": "object" } } }, "type": "object" }, "genre": { "description": "Included with ?include=genre.", "properties": { "data": { "properties": { "type": { "type": "string", "example": "genres" }, "id": { "type": "string", "format": "uuid" } }, "type": "object", "nullable": true } }, "type": "object" }, "manufacturer": { "description": "Included with ?include=manufacturer.", "properties": { "data": { "properties": { "type": { "type": "string", "example": "manufacturers" }, "id": { "type": "string", "format": "uuid" } }, "type": "object", "nullable": true } }, "type": "object" }, "brand": { "description": "Included with ?include=brand.", "properties": { "data": { "properties": { "type": { "type": "string", "example": "brands" }, "id": { "type": "string", "format": "uuid" } }, "type": "object", "nullable": true } }, "type": "object" }, "year": { "description": "Included with ?include=year.", "properties": { "data": { "properties": { "type": { "type": "string", "example": "years" }, "id": { "type": "string", "format": "uuid" } }, "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "Player": { "title": "Player", "description": "A player resource", "properties": { "type": { "type": "string", "example": "players" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "Michael Jordan" }, "first_name": { "type": "string", "example": "Michael" }, "last_name": { "type": "string", "example": "Jordan" }, "position": { "type": "string", "example": "Shooting Guard", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "Team": { "title": "Team", "description": "A team resource", "properties": { "type": { "type": "string", "example": "teams" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "Chicago Bulls" }, "city": { "type": "string", "example": "Chicago", "nullable": true }, "abbreviation": { "type": "string", "example": "CHI", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "PaginationLinks": { "title": "Pagination Links", "description": "JSON:API pagination links", "properties": { "first": { "type": "string", "format": "uri", "nullable": true }, "last": { "type": "string", "format": "uri", "nullable": true }, "prev": { "type": "string", "format": "uri", "nullable": true }, "next": { "type": "string", "format": "uri", "nullable": true } }, "type": "object" }, "PaginationMeta": { "title": "Pagination Meta", "description": "JSON:API pagination metadata", "properties": { "current_page": { "type": "integer", "example": 1 }, "from": { "type": "integer", "example": 1 }, "to": { "type": "integer", "example": 25 }, "per_page": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 100 }, "last_page": { "type": "integer", "example": 4 } }, "type": "object" }, "ListingScopeMeta": { "title": "Listing Scope Meta", "description": "Names the row scope a listing applied, so a scoped total is not misread as a count of the whole catalog.", "properties": { "applied": { "description": "Identifier of the scope the listing applied.", "type": "string", "example": "root_sets_only", "enum": [ "root_sets_only", "all_sets", "child_sets_of_parent" ] }, "description": { "description": "Human-readable explanation of the applied scope, including how to widen it.", "type": "string", "example": "Only sets without a parent are listed, so parallels, inserts, autograph subsets and variations are omitted. This is a default scope, not a limit on your account. Add ?scope=all to list every set, or ?parent_id={id} to list one set's children." } }, "type": "object" }, "ErrorResponse": { "title": "Error Response", "description": "JSON:API error response format", "properties": { "errors": { "type": "array", "items": { "properties": { "id": { "description": "Unique error identifier", "type": "string" }, "status": { "description": "HTTP status code", "type": "string" }, "code": { "description": "Application-specific error code", "type": "string" }, "title": { "description": "Short error summary", "type": "string" }, "detail": { "description": "Detailed error description", "type": "string" }, "source": { "properties": { "pointer": { "description": "JSON pointer to error source", "type": "string" }, "parameter": { "description": "Parameter causing the error", "type": "string" } }, "type": "object" } }, "type": "object" } } }, "type": "object" }, "Attribute": { "title": "Attribute", "description": "An attribute definition resource", "properties": { "type": { "type": "string", "example": "attributes" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "attribute": { "type": "string", "example": "Autograph" }, "name": { "type": "string", "example": "Autograph" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "Brand": { "title": "Brand", "description": "A brand resource", "properties": { "type": { "type": "string", "example": "brands" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "Topps" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "Manufacturer": { "title": "Manufacturer", "description": "A manufacturer resource", "properties": { "type": { "type": "string", "example": "manufacturers" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "Topps Company" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "Year": { "title": "Year", "description": "A year resource", "properties": { "type": { "type": "string", "example": "years" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "year": { "type": "string", "example": "1989" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "Genre": { "title": "Genre", "description": "A genre resource", "properties": { "type": { "type": "string", "example": "genres" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "Baseball" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "ObjectAttribute": { "title": "Object Attribute", "description": "An object attribute instance resource linking an attribute to a specific object", "properties": { "type": { "type": "string", "example": "object-attributes" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "attribute_id": { "type": "string", "format": "uuid" }, "attribute_value": { "type": "string", "example": "Authenticated" }, "object_type": { "type": "string", "example": "App\\Models\\Card" }, "object_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "PlayerTeam": { "title": "Player Team", "description": "A player-team relationship resource", "properties": { "type": { "type": "string", "example": "playerteams" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "name": { "type": "string", "example": "Michael Jordan - Chicago Bulls" }, "player_id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "SetSource": { "title": "Set Source", "description": "A set source tracking resource", "properties": { "type": { "type": "string", "example": "set_sources" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "source_url": { "type": "string", "format": "url", "example": "https://example.com/checklist" }, "source_name": { "type": "string", "example": "CardboardConnection", "nullable": true }, "source_type": { "type": "string", "example": "checklist", "enum": [ "checklist", "metadata", "images" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "type": "object" } }, "type": "object" }, "SetTodo": { "title": "Set Todo", "description": "A workflow step todo resource", "properties": { "type": { "type": "string", "example": "set_todos" }, "id": { "type": "string", "format": "uuid" }, "attributes": { "properties": { "step": { "description": "Workflow step identifier; see WorkflowStep enum for valid values.", "type": "string", "example": "fetch" }, "status": { "type": "string", "example": "in_progress", "enum": [ "pending", "in_progress", "completed", "skipped", "blocked", "review" ] }, "sort_order": { "type": "integer", "example": 1 }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_by": { "type": "string", "example": "admin", "nullable": true }, "notes": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" }, "AuditLog": { "title": "Audit Log", "description": "An audit log event resource", "properties": { "type": { "type": "string", "example": "audit_logs" }, "id": { "type": "integer", "example": 12345 }, "attributes": { "properties": { "event_type": { "type": "string", "example": "agent_spawned", "maxLength": 50 }, "auditable_type": { "type": "string", "example": "set", "nullable": true, "enum": [ "set", "card", "player", "team", "playerteam" ] }, "auditable_id": { "type": "string", "format": "uuid", "nullable": true }, "agent_id": { "type": "string", "example": "agent-abc-123", "nullable": true, "maxLength": 100 }, "data": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } }, "type": "object" } }, "responses": { "SubscriptionRequired": { "description": "Payment Required — the authenticated user's billing account is not subscribed (an expired trial that never converted). The API key is preserved; access resumes automatically once the subscription is active again. Emitted by the EnsureActiveSubscription middleware (issue #2038).", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "402", "code": "SUBSCRIPTION_REQUIRED", "title": "Payment Required", "detail": "An active subscription is required to access this endpoint. Subscribe or update your billing to restore access; your API key is preserved and access resumes automatically once your subscription is active." } ] } } } }, "InvalidQueryParameter": { "description": "Bad Request — the query string contains a parameter this endpoint does not accept, or the requested page size exceeds the maximum of 100. Unrecognized parameters are rejected rather than ignored, so a misspelled filter can never silently return the full unfiltered collection (issue #2305). One error object is returned per offending parameter, each naming it in `source.parameter`, and the `detail` lists every parameter the endpoint does accept.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "400", "code": "INVALID_PARAMETER", "title": "Unknown query parameter", "detail": "The query parameter 'name' is not supported by this endpoint. Accepted parameters are: first_name, full_name, include, last_name, limit, order_by, page, per_page, sort.", "source": { "parameter": "name" } } ] } } } }, "RateLimited": { "description": "Too Many Requests — the caller has exhausted its rate-limit budget for the current window. Every published endpoint except `GET /health` and `POST /webhooks/stripe` is throttled by the `api` limiter, whose quota is chosen per caller: anonymous requests (no bearer token) get the anonymous tier, and an authenticated request gets, in precedence order, its OAuth client's per-client `rate_limit` override, the internal-caller pool if the client row is flagged `is_internal`, or the default authenticated tier. See config/ratelimiting.php for the current values. A few public endpoints stack a tighter named per-IP limiter on top of the `api` bucket (signup, verification resend, invite validation), so they can return a 429 well before the `api` quota is spent — those operations describe the extra limit in their own description.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "example": 42 } }, "X-RateLimit-Limit": { "description": "Maximum number of requests allowed in the current window.", "schema": { "type": "integer", "example": 2000 } }, "X-RateLimit-Remaining": { "description": "Requests remaining in the current window (0 on a 429).", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "Unix timestamp at which the current window resets. Present on EVERY throttled-route response, not just this 429 (issue #2343), so a client can derive the length of its rate-limit window without tripping a limit first.", "schema": { "type": "integer", "example": 1756051200 } } }, "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "429", "code": "TOO-MANY-REQUESTS", "title": "Too many requests.", "detail": "You have sent too many requests in a given amount of time. Please retry after a short delay." } ] } } } }, "ValidationError": { "description": "Unprocessable Entity — the request document failed validation. One error object is returned per offending field per rule, each naming the field with an RFC 6901 JSON Pointer in `source.pointer` (bare field names are rooted under `/data/attributes/`). The `detail` carries the human-readable validation message.", "content": { "application/vnd.api+json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "status": "422", "code": "VALIDATION-FAILED", "title": "Validation failed", "detail": "The name field is required.", "source": { "pointer": "/data/attributes/name" } }, { "status": "422", "code": "VALIDATION-FAILED", "title": "Validation failed", "detail": "The selected year id is invalid.", "source": { "pointer": "/data/attributes/year_id" } } ] } } } } }, "securitySchemes": { "bearer": { "type": "http", "description": "Bearer token authentication. Obtain tokens via Personal Access Token generation (simple - see API-KEY-GUIDE.md) or OAuth 2.0 client credentials flow (see oauth.md). Supports scopes: read, read:published, read:draft, read:all-status, write, delete, internal.", "bearerFormat": "JWT", "scheme": "bearer" } } }, "security": [ { "bearer": [] } ], "tags": [ { "name": "Authentication", "description": "API authentication via Bearer tokens. Generate Personal Access Tokens for simple use cases or use OAuth 2.0 client credentials flow for programmatic access." }, { "name": "Health", "description": "Health" }, { "name": "Internal", "description": "Internal" }, { "name": "Webhooks", "description": "Webhooks" }, { "name": "Attributes v1", "description": "Attributes v1" }, { "name": "Billing", "description": "Billing" }, { "name": "Brands v1", "description": "Brands v1" }, { "name": "Cards v1", "description": "Cards v1" }, { "name": "Card Images", "description": "Card Images" }, { "name": "Genres v1", "description": "Genres v1" }, { "name": "Manufacturers v1", "description": "Manufacturers v1" }, { "name": "ObjectAttributes v1", "description": "ObjectAttributes v1" }, { "name": "Players v1", "description": "Players v1" }, { "name": "PlayerTeams v1", "description": "PlayerTeams v1" }, { "name": "Sets v1", "description": "Sets v1" }, { "name": "Set Sources v1", "description": "Set Sources v1" }, { "name": "Statistics v1", "description": "Statistics v1" }, { "name": "Teams v1", "description": "Teams v1" }, { "name": "Years v1", "description": "Years v1" }, { "name": "Sets v2", "description": "Sets v2" }, { "name": "Version", "description": "Version" } ] }