{"openapi":"3.1.0","info":{"title":"TokPortal Public API","version":"2026-05-25","description":"Non-breaking public API contract for TokPortal developer integrations. This spec is the first generated surface for SDKs, CLI, MCP, and docs.\n\nAI: /ai uses a separate USD wallet and quoted, permission-checked operations. Discover models and their schemas, obtain a quote, then execute with the approved maximum USD cost and an Idempotency-Key. An unavailable capability fails closed. AI endpoints do not advertise the legacy dry-run contract.\n\nSANDBOX (non-AI endpoints): every non-GET operation accepts the `X-TokPortal-Dry-Run: true` header. A dry run runs the full validation and pricing path and stops before the first write; nothing is created, no credits are debited, no webhook fires, and no operator sees it. The response keeps the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and `credits_would_charge` with the real price. Errors are byte-identical to the real call: explore an operation, read its real errors, and see what it would cost BEFORE spending anything, because management credits are debited at creation and there is no refund path for those credits. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic; reuse one in a real call and you get DRY_RUN_ID_IN_LIVE_REQUEST rather than a confusing not-found."},"servers":[{"url":"https://app.tokportal.com/api/ext","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Profile"},{"name":"Reference"},{"name":"Credits"},{"name":"Bundles"},{"name":"Account Configuration"},{"name":"Videos"},{"name":"Accounts"},{"name":"Warming"},{"name":"Uploads"},{"name":"Analytics"},{"name":"Comments"},{"name":"Webhooks"},{"name":"AI","description":"Model discovery, quoted generation, assets and a separate USD wallet."}],"paths":{"/me":{"get":{"operationId":"getCurrentUser","summary":"Get authenticated user","description":"Returns the authenticated workspace: profile, role, analytics access tier and live credit balance. Call once at the start of a session to learn what this key can do.","tags":["Profile"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Authenticated user profile and credit balance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/me\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/me', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/me',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/me\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"patch":{"operationId":"updateCurrentUserSettings","summary":"Update safe workspace settings","description":"Updates client-owned workspace profile fields used by Operator context. Does not expose auth, role, credit, staff, or manager settings.","tags":["Profile"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCurrentUserSettingsRequest"}}}},"responses":{"200":{"description":"Updated safe workspace settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCurrentUserSettingsResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid workspace setting.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/me\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"company_name\": \"company_name\",\n \"website\": \"website\",\n \"company_niche\": \"company_niche\",\n \"organic_strategy\": \"organic_strategy\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/me', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"company_name\": \"company_name\",\n \"website\": \"website\",\n \"company_niche\": \"company_niche\",\n \"organic_strategy\": \"organic_strategy\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/me',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"company_name\\\": \\\"company_name\\\",\\n \\\"website\\\": \\\"website\\\",\\n \\\"company_niche\\\": \\\"company_niche\\\",\\n \\\"organic_strategy\\\": \\\"organic_strategy\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/me\", strings.NewReader(\"{\\n \\\"company_name\\\": \\\"company_name\\\",\\n \\\"website\\\": \\\"website\\\",\\n \\\"company_niche\\\": \\\"company_niche\\\",\\n \\\"organic_strategy\\\": \\\"organic_strategy\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/managed-subscription":{"get":{"operationId":"getAccountManagedSubscription","summary":"Get TokPortal Coverage status","description":"Returns the effective TokPortal Coverage status, current 30-day period, account-specific rate, unpaid periods, task access, and an exact timestamped reactivation quote for one eligible saved account. At current_period_end, status and task_access change immediately even if recorded_status remains included or active for a few minutes until the renewal worker persists the transition; period_expired makes that boundary explicit. A zero-credit quote is valid. Use its current_period_end and lock_version snapshot for reactivation. An eligible TikTok or Instagram account created before the global Coverage cutoff is grandfathered and has no subscription record. A missing record can also mean the account is not Coverage-eligible or has not reached delivery, so clients must not infer grandfathering from a generic 404. Coverage is independent from bundle completion or closure.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"TokPortal Coverage status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedAccountSubscriptionResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account or coverage record not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/managed-subscription/reactivate":{"post":{"operationId":"reactivateAccountManagedSubscription","summary":"Reactivate TokPortal Coverage","description":"Reactivates TokPortal Coverage from an explicit GET snapshot, and debits the projected unpaid 30-day periods — read the quote from getAccountManagedSubscription and confirm the amount with the user first. Reactivation is free while the current billing period is already paid or included; Coverage benefits and tasks remain paused until reactivation. At and after current_period_end, the endpoint accepts the effective lapsed state even if recorded_status has not yet been updated by the renewal worker, and charges exactly the projected unpaid periods without adding an extra period. The expected credits, period end, and lock version are checked atomically before any debit or task resume. Scheduled videos receive new future dates while preserving their cadence.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedAccountSubscriptionReactivationRequest"}}}},"responses":{"200":{"description":"Coverage reactivated and withheld work resumed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedAccountSubscriptionReactivationResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits. The response details include the exact required amount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Account or coverage record not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Coverage is not paused, the account is unavailable, or the quote changed. Fetch a fresh snapshot before retrying QUOTE_CHANGED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription/reactivate\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Idempotency-Key: reactivateAccountManagedSubscription-example-1\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"expected_credits\": 25,\n \"expected_current_period_end\": \"2026-06-01T00:00:00Z\",\n \"expected_lock_version\": 25\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription/reactivate', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n 'Idempotency-Key': 'reactivateAccountManagedSubscription-example-1',\n },\n body: JSON.stringify({\n \"expected_credits\": 25,\n \"expected_current_period_end\": \"2026-06-01T00:00:00Z\",\n \"expected_lock_version\": 25\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription/reactivate',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"], \"Idempotency-Key\": \"reactivateAccountManagedSubscription-example-1\"},\n json=json.loads(\"{\\n \\\"expected_credits\\\": 25,\\n \\\"expected_current_period_end\\\": \\\"2026-06-01T00:00:00Z\\\",\\n \\\"expected_lock_version\\\": 25\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription/reactivate\", strings.NewReader(\"{\\n \\\"expected_credits\\\": 25,\\n \\\"expected_current_period_end\\\": \\\"2026-06-01T00:00:00Z\\\",\\n \\\"expected_lock_version\\\": 25\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Idempotency-Key\", \"reactivateAccountManagedSubscription-example-1\")\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/managed-subscription/cancel":{"post":{"operationId":"cancelAccountManagedSubscription","summary":"Pause TokPortal Coverage","description":"Immediately blocks new and ongoing TokPortal work for the account. Payments are not refunded. If a paid or included current period remains, reactivation is free until its original end. Otherwise it costs exactly the unpaid 30-day periods at the rate returned by the Coverage status endpoint.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Coverage paused and current work withheld.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManagedAccountSubscriptionCancellationResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Account or coverage record not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Coverage cannot be cancelled in its current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription/cancel\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Idempotency-Key: cancelAccountManagedSubscription-example-1\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription/cancel', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Idempotency-Key': 'cancelAccountManagedSubscription-example-1',\n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription/cancel',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"], \"Idempotency-Key\": \"cancelAccountManagedSubscription-example-1\"}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/managed-subscription/cancel\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Idempotency-Key\", \"cancelAccountManagedSubscription-example-1\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/countries":{"get":{"operationId":"listCountries","summary":"List available countries","description":"Lists the valid `country` values for bundle creation. Most are ISO-3166-1 alpha-2 (FR, DE, BR), but TokPortal's own codes are the authority and two of them are not alpha-2: the United States is `USA` and the United Kingdom is `UK`. Their ISO aliases `US` and `GB` are accepted and resolved to those two, so send a code from this list verbatim and never assume alpha-2. Call before createBundle or createBundlesBulk: `country` is validated against this list, and a full country name such as \"United States\" is rejected. `videos_only_countries` applies only to video orders on an existing account and is never valid for /bundles/bulk.","tags":["Reference"],"security":[],"responses":{"200":{"description":"Country availability by order type. data contains countries available for new account creation; videos_only_countries contains countries available for video orders on an existing account. Fully disabled countries are excluded from both lists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountriesResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/countries\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/countries', {\n method: 'GET',\n headers: {\n \n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/countries',\n headers={}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/countries\", nil)\nresp, err := http.DefaultClient.Do(req)"}]}},"/platforms":{"get":{"operationId":"listPlatforms","summary":"List available platforms","description":"Lists the orderable platforms and, per video type, the exact required and optional fields. Call before configuring any slot: TikTok carousels require `tiktok_sound_url`, Instagram posts and reels require `instagram_content_type`, and a story takes exactly one of `video_url` or `story_image_url` and no description. Only TikTok and Instagram can be ordered; YouTube fields exist on the video schema but YouTube bundles are rejected with YOUTUBE_DELAYED.","tags":["Reference"],"security":[],"responses":{"200":{"description":"Supported social platforms.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/platforms\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/platforms', {\n method: 'GET',\n headers: {\n \n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/platforms',\n headers={}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/platforms\", nil)\nresp, err := http.DefaultClient.Do(req)"}]}},"/credit-costs":{"get":{"operationId":"getCreditCosts","summary":"Get credit pricing","description":"Authoritative live credit prices and workspace cohort. Call it immediately before any purchase and never hard-code or recall a price. Not every key is orderable: `youtube_account_creation` is listed for reference only (YouTube bundles are rejected with YOUTUBE_DELAYED), and `niche_warming` and `deep_warming` are legacy prices published for backward compatibility only — they are not products a caller may choose, and `advanced_warming` (Advanced Niche Warming, priced per niche target) is the only warming TokPortal sells. `managed_account_subscription` (TokPortal Coverage) recurs every 30 days per account after the included first period, so a multi-account quote must include it as a monthly cost. There is no dry-run endpoint: assemble the total from this table (account setup + video slots + Advanced Niche Warming targets + edit slots + paid video options), apply the returned cohort and contract_bundle_allowance, and confirm it with the user before creating anything.","tags":["Credits"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"The authenticated workspace's effective action-price table, its cohort and transition state, both cohort dates, TokPortal Coverage price and account eligibility, the saved-account credential-reveal cutoff, Account Owning Fee approval threshold and legacy/new agreement rates, and the 1-credit Comments API task. credential_reveal is an informational fallback only: the exact first-access quote is account-specific and is returned by HTTP 428 or 409 from the credential or verification-code endpoint. The former per-bundle moderation add-on is unavailable. managed_account_subscription remains the stable technical cost key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditCostsResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/credit-costs\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/credit-costs', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/credit-costs',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/credit-costs\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/credits/balance":{"get":{"operationId":"getCreditBalance","summary":"Get credit balance","description":"Returns the currently spendable credit balance and upcoming expirations. Check it before any purchase: a 402 on a mutation means this was short.","tags":["Credits"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Current credit balance.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/credits/balance\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/credits/balance', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/credits/balance',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/credits/balance\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/credits/history":{"get":{"operationId":"listCreditTransactions","summary":"List credit transactions","description":"Paginated ledger of every credit debit and refund, newest first. Use it to reconcile what a bundle or batch actually cost, since server-side pricing (workspace cohort, contract allowance) can differ from the list price.","tags":["Credits"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"date_from","in":"query","required":false,"description":"Filter transactions created on or after this date.","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","required":false,"description":"Filter transactions created before the day after this date.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Paginated credit transaction history.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/credits/history?page=example&per_page=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/credits/history?page=example&per_page=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/credits/history?page=example&per_page=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/credits/history?page=example&per_page=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles":{"get":{"operationId":"listBundles","summary":"List bundles","description":"Lists your bundles with their lifecycle status and the computed `next_action` (`configure_account`, `configure_videos`, `publish_bundle`, or null). `next_action` is the recommended way to find what a bundle still needs.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","required":false,"description":"Filter by bundle status.","schema":{"type":"string"}},{"name":"bundle_type","in":"query","required":false,"schema":{"type":"string","enum":["account_only","account_and_videos","videos_only"]}},{"name":"platform","in":"query","required":false,"schema":{"type":"string","enum":["tiktok","instagram"]}},{"name":"external_ref","in":"query","required":false,"schema":{"type":"string"}},{"name":"account_status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated bundle list.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/bundles?page=example&per_page=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles?page=example&per_page=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/bundles?page=example&per_page=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/bundles?page=example&per_page=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"post":{"operationId":"createBundle","summary":"Create a bundle","description":"Creates and pays an account-only, account-and-videos, or videos-only bundle in one atomic creation checkout. Credits are debited immediately on a successful POST, not when the bundle is published, and THERE IS NO CANCELLATION OR REFUND PATH — read getCreditCosts and getCreditBalance and confirm the total with the user before calling. One bundle produces exactly one account; order several accounts with createBundlesBulk. TikTok and Instagram only: a YouTube bundle is rejected with YOUTUBE_DELAYED even though getCreditCosts lists a YouTube price. Advanced Niche Warming requires wants_advanced_warming: true ALONGSIDE advanced_warming_terms or advanced_warming_terms_count; targets sent without the flag are refused with ADVANCED_WARMING_FLAG_REQUIRED, never charged and dropped. Send the term list or the count, not two quantities that disagree (ADVANCED_WARMING_COUNT_MISMATCH), and send distinct terms — anything removed by cleanup fails the call with ADVANCED_WARMING_TERMS_REJECTED rather than silently reducing what you receive and pay for. Credit cost is calculated server-side from the workspace cohort and any contract_bundle_allowance returned by getCreditCosts. A qualifying allowance slot is consumed in the same transaction as the credit debit; failed requests consume nothing. The exact new-customer and saved-account cutoff is the immutable production PRE-migration instant returned by getCreditCosts. A real TikTok or Instagram saved account created on or after that cutoff receives its first 30 days of TokPortal Coverage included unless the creation response marks it contractually exempt, and Coverage then recurs every 30 days per account at the managed_account_subscription price. For Advanced Niche Warming, pass advanced_warming_terms now, or buy a target count with advanced_warming_terms_count at the effective workspace rate and configure the targets later via PUT /bundles/{id}/warming-terms — one or the other, always with wants_advanced_warming: true. Set the targets BEFORE publishing: publishBundle refuses a bundle whose warming has no targets (ADVANCED_WARMING_NOT_CONFIGURED), and a purchase left unconfigured is not refunded. The bundle is created in pending_setup and still needs configureBundleAccount and publishBundle. Delivered videos are approved automatically unless you send auto_finalize_videos: false — the response echoes the settlement mode as review_mode ('auto' or 'manual'), plus a one-off review_mode_notice when you left the choice to the default. external_ref is a client correlation and duplicate-detection aid, not a retry mechanism; only Idempotency-Key provides exact request replay.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBundleRequest"}}}},"responses":{"201":{"description":"Bundle created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBundleResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid request body or business rule violation. Warming-specific codes: ADVANCED_WARMING_FLAG_REQUIRED (advanced_warming_terms or advanced_warming_terms_count sent without wants_advanced_warming: true), ADVANCED_WARMING_TERMS_REJECTED (a term was removed as a duplicate or for its length, so fewer targets would have been delivered and billed than requested — details.dropped_terms lists them), ADVANCED_WARMING_COUNT_MISMATCH (advanced_warming_terms and advanced_warming_terms_count state different quantities), ADVANCED_WARMING_TERMS (count outside 3-30 or not a multiple of 3), ADVANCED_WARMING_PLATFORM, WARMING_CONFLICT. UNKNOWN_FIELD when the body carries a field TokPortal does not recognise: this write is a full replace, so an unrecognised field is refused rather than dropped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Duplicate account bundle, invalid state, or BUNDLE_PRICING_CHANGED. A pricing change charges nothing and creates nothing; fetch getCreditCosts again and retry with a new Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Workspace bundle capacity is on cooldown. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"bundle_type\": \"account_only\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"bundle_type\": \"account_only\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"bundle_type\\\": \\\"account_only\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles\", strings.NewReader(\"{\\n \\\"bundle_type\\\": \\\"account_only\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/bulk":{"post":{"operationId":"createBundlesBulk","summary":"Create bundles in bulk","description":"Creates and pays several bundles in one atomic creation checkout. Credits are debited immediately on a successful POST, not at publication, and THERE IS NO CANCELLATION OR REFUND PATH — read getCreditCosts and getCreditBalance and confirm the total with the user before calling, because the loss is multiplied by accounts_count and platforms. Each bundle produces exactly one account. Warming targets and credits are charged per account, not per batch. Advanced Niche Warming requires wants_advanced_warming: true ALONGSIDE advanced_warming_terms or advanced_warming_terms_count; targets sent without the flag are refused with ADVANCED_WARMING_FLAG_REQUIRED for the whole batch, never charged and dropped. Send the term list or the count, not two quantities that disagree (ADVANCED_WARMING_COUNT_MISMATCH), and send distinct terms — anything removed by cleanup fails the call with ADVANCED_WARMING_TERMS_REJECTED. The complete batch is checked against rolling workspace capacity and any contract_bundle_allowance returned by getCreditCosts. Qualifying allowance slots are consumed in deterministic bundle-ID order in the same transaction as all debits; if any bundle fails, the entire batch rolls back and consumes nothing, so never split a 429 capacity-cooldown batch into parallel calls. A batch crossing the final allowance slot receives the contract price only for the remaining qualifying bundles. For Advanced Niche Warming, pass advanced_warming_terms, using the same terms for every account, or buy a per-account target count with advanced_warming_terms_count and configure each bundle's targets later via PUT /bundles/{id}/warming-terms — one or the other, always with wants_advanced_warming: true. Every bundle is returned in pending_setup with no username: each one still needs configureBundleAccount and publishBundle before any work starts. Delivered videos are approved automatically for every bundle in the batch unless you send auto_finalize_videos: false — the response echoes review_mode ('auto' or 'manual'), plus a one-off review_mode_notice when you left the choice to the default. external_ref is one optional batch-level reference copied to the resulting bundles, not a unique per-bundle key or a retry mechanism; use returned bundle IDs for identity and Idempotency-Key for exact replay.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBulkBundlesRequest"}}}},"responses":{"201":{"description":"Bulk bundle creation result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBulkBundlesResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid request body or business rule violation. Warming-specific codes: ADVANCED_WARMING_FLAG_REQUIRED (advanced_warming_terms or advanced_warming_terms_count sent without wants_advanced_warming: true), ADVANCED_WARMING_TERMS_REJECTED (a term was removed as a duplicate or for its length, so fewer targets would have been delivered and billed than requested — details.dropped_terms lists them), ADVANCED_WARMING_COUNT_MISMATCH (advanced_warming_terms and advanced_warming_terms_count state different quantities), ADVANCED_WARMING_TERMS (count outside 3-30 or not a multiple of 3), ADVANCED_WARMING_PLATFORM, WARMING_CONFLICT. UNKNOWN_FIELD when the body carries a field TokPortal does not recognise: this write is a full replace, so an unrecognised field is refused rather than dropped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"BUNDLE_PRICING_CHANGED means the full batch was rolled back with no charge and no allowance consumption. In details, `required` is the recomputed price of ONE bundle (the first that disagreed) while `quoted` is the total for the whole batch — `required_scope` and `quoted_scope` label which is which, and `batch_bundles` carries the count. Fetch getCreditCosts again and retry with a new Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"The full batch would exceed rolling workspace capacity. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/bulk\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"platforms\": [\n \"tiktok\"\n ],\n \"country\": \"USA\",\n \"accounts_count\": 25\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/bulk', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"platforms\": [\n \"tiktok\"\n ],\n \"country\": \"USA\",\n \"accounts_count\": 25\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/bulk',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"platforms\\\": [\\n \\\"tiktok\\\"\\n ],\\n \\\"country\\\": \\\"USA\\\",\\n \\\"accounts_count\\\": 25\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/bulk\", strings.NewReader(\"{\\n \\\"platforms\\\": [\\n \\\"tiktok\\\"\\n ],\\n \\\"country\\\": \\\"USA\\\",\\n \\\"accounts_count\\\": 25\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}":{"get":{"operationId":"getBundle","summary":"Get a bundle","description":"Full state of one bundle: status, account configuration, video slot counts, warming purchase, cancellation and remake history, and `next_action`. A remade bundle keeps the same id while its `saved_account_id` changes.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Bundle details.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"patch":{"operationId":"updateBundle","summary":"Update bundle settings","description":"Updates mutable bundle metadata: title, external_ref, and auto_finalize_videos. auto_finalize_videos true (the default) approves every delivered video automatically — it counts as final on arrival; set it to false to hold each delivered video for your review, approving with finalizeBundleVideo or pushing back with requestBundleVideoCorrections yourself. Note that anything left in review is auto-finalized about 72 hours after entering it either way.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchBundleRequest"}}}},"responses":{"200":{"description":"Bundle updated.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid patch body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"Bundle belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Duplicate external_ref.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"auto_finalize_videos\": false,\n \"external_ref\": \"external_ref\",\n \"title\": \"Launch campaign\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"auto_finalize_videos\": false,\n \"external_ref\": \"external_ref\",\n \"title\": \"Launch campaign\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"auto_finalize_videos\\\": false,\\n \\\"external_ref\\\": \\\"external_ref\\\",\\n \\\"title\\\": \\\"Launch campaign\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", strings.NewReader(\"{\\n \\\"auto_finalize_videos\\\": false,\\n \\\"external_ref\\\": \\\"external_ref\\\",\\n \\\"title\\\": \\\"Launch campaign\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/publish":{"post":{"operationId":"publishBundle","summary":"Publish a bundle","description":"Submits a fully configured bundle to the account-manager marketplace, which is what actually starts the work. Requires status `pending_setup`, a complete account profile, and at least one configured video on an `account_and_videos` bundle — call getBundlePublishReadiness first, it returns every blocker without debiting. A due Coverage period renews here, so this call can debit credits even though the bundle's own cost was charged at creation. Irreversible once a manager accepts: unpublishBundle only works before that, and never refunds. Publish-time date guard: any slot whose target date has already reached today or the past is moved forward to the earliest allowed day (today+1 with a delivered or existing account, today+3 while the account is still being created, in UTC), respecting the 3-videos-per-day-per-bundle cap — an overflowing day spills to the next one. Slots still in the future are NOT moved. This never fails the publish. When something moved, the response carries `adjusted_videos` — one entry per moved slot, `{video_id, position, previous_date, new_date}` — and `adjusted_videos_note`. Read them back instead of assuming the schedule you sent survived. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Publish result.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Bundle is not ready or is in an invalid state. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Workspace publication capacity is on cooldown. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/publish\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/publish', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/publish',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/publish\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/publish-readiness":{"get":{"operationId":"getBundlePublishReadiness","summary":"Check bundle publish readiness","description":"Returns every current publish blocker without mutating the bundle, settling Coverage, or debiting credits. MANAGED_ACCOUNT_TASK_BLOCKED includes details.account_id and details.reason. Fetch GET /accounts/{account_id}/managed-subscription for the authoritative state and exact reactivation quote. A due included or active period can temporarily appear blocked until renewal is settled by cron or an approved mutation.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Readiness blockers and ready flag.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/publish-readiness\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/publish-readiness', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/publish-readiness',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/publish-readiness\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/unpublish":{"post":{"operationId":"unpublishBundle","summary":"Unpublish a bundle","description":"Returns a published bundle to `pending_setup` so its account configuration can be edited again. Only works while the bundle is published and no account manager has accepted it (409 otherwise). Credits are NOT refunded and this is not a cancellation: there is no API path to cancel a bundle or recover its credits.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Unpublish result.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Bundle is in an invalid state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/unpublish\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/unpublish', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/unpublish',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/unpublish\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/add-video-slots":{"post":{"operationId":"addVideoSlots","summary":"Add video slots to a bundle","description":"Buys additional video slots on an existing bundle and debits credits immediately (see `video_upload` in getCreditCosts). The slots are non-refundable and there is no cancellation path for this purchase — confirm the exact cost with the user before calling. Configure the new positions with configureBundleVideo, then publish them.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuantityRequest"}}}},"responses":{"200":{"description":"Created video slots.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid quantity or bundle type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/add-video-slots\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"quantity\": 1\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/add-video-slots', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"quantity\": 1\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/add-video-slots',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"quantity\\\": 1\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/add-video-slots\", strings.NewReader(\"{\\n \\\"quantity\\\": 1\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/add-edit-slots":{"post":{"operationId":"addEditSlots","summary":"Add VIDEO-editing slots to a bundle","description":"Buys video-editing slots — professional editing of a video by the account manager — and debits credits immediately (see `video_edit` in getCreditCosts). Non-refundable, with no cancellation path; confirm the exact cost with the user before calling. `edits_quantity` cannot exceed the bundle's `videos_quantity`, one video consumes at most one slot, and a slot is only consumed when that video carries `editing_instructions`. This has nothing to do with editing an account profile — use createAccountEditRequest for that.","tags":["Bundles"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuantityRequest"}}}},"responses":{"200":{"description":"Created edit slots.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid quantity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/add-edit-slots\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"quantity\": 1\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/add-edit-slots', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"quantity\": 1\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/add-edit-slots',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"quantity\\\": 1\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/add-edit-slots\", strings.NewReader(\"{\\n \\\"quantity\\\": 1\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/account":{"get":{"operationId":"getBundleAccount","summary":"Get bundle account configuration","description":"Returns the current account-profile configuration of a bundle (username, visible name, biography, picture) and its listing status. Read it before configureBundleAccount to see what is already set and whether the profile is still editable.","tags":["Account Configuration"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Account configuration.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Bundle or account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"put":{"operationId":"configureBundleAccount","summary":"Configure bundle account profile","description":"Sets the profile of an account that has NOT been delivered yet: username, visible name, biography, profile picture, and link-in-bio on Instagram bundles. Only valid while the bundle is `pending_setup` or `configured` — unpublish first to edit after publishing, and use createAccountEditRequest for an account that is already delivered. This is a full replacement: any field you omit is written back as null, so re-send the whole profile when you change one part of it. `link_in_bio` is stored on Instagram bundles only. On any other platform it is accepted but not stored, and the response says so explicitly through `_warnings` while echoing `link_in_bio: null` — read both back. For backward compatibility this endpoint also accepts the exact purchased advanced_warming_terms list, but PUT /bundles/{id}/warming-terms is the recommended one-shot deferred-target endpoint because it remains available at any account status. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription. A new account that has not produced a saved account yet remains configurable before delivery.","tags":["Account Configuration"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureAccountRequest"}}}},"responses":{"200":{"description":"Configured account.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid account profile, or advanced_warming_terms does not match the purchased target count (ADVANCED_WARMING_TERMS). UNKNOWN_FIELD when the body carries an unrecognised field: this is a full replace, so a misspelled field would otherwise erase the value it was meant to set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or account not found, or no warming session to configure (WARMING_SESSION_NOT_FOUND).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Account status does not allow configuration, or the warming targets are already set (WARMING_TERMS_ALREADY_SET). If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"username\": \"USA\",\n \"visible_name\": \"visible_name\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account', {\n method: 'PUT',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"username\": \"USA\",\n \"visible_name\": \"visible_name\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PUT',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"username\\\": \\\"USA\\\",\\n \\\"visible_name\\\": \\\"visible_name\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PUT\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account\", strings.NewReader(\"{\\n \\\"username\\\": \\\"USA\\\",\\n \\\"visible_name\\\": \\\"visible_name\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/account/corrections":{"post":{"operationId":"requestBundleAccountCorrections","summary":"Request account corrections","description":"Moves an in-review account back to pending corrections with reviewer feedback.","tags":["Account Configuration"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountCorrectionsRequest"}}}},"responses":{"200":{"description":"Account corrections requested.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid correction body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Account is not in review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account/corrections\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"comment\": \"Please review this item.\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account/corrections', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"comment\": \"Please review this item.\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account/corrections',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"comment\\\": \\\"Please review this item.\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account/corrections\", strings.NewReader(\"{\\n \\\"comment\\\": \\\"Please review this item.\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/account/finalize":{"post":{"operationId":"finalizeBundleAccount","summary":"Finalize account review","description":"Approves an in-review account and marks it finalized.","tags":["Account Configuration"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Account finalized.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Account is not in review.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account/finalize\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account/finalize', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account/finalize',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/account/finalize\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos":{"get":{"operationId":"listBundleVideos","summary":"List bundle video slots","description":"Lists every video slot of a bundle with its position, configuration, schedule and review status. Positions are 1-based and run up to the bundle's `videos_quantity`.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Video slots for the bundle.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/{position}":{"get":{"operationId":"getBundleVideo","summary":"Get video slot configuration","description":"Returns one video slot's configuration, schedule, review status and post link. Use it to check whether a slot is still inside its review window before finalizing it.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"position","in":"path","required":true,"description":"1-based video slot position.","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Video slot configuration.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Bundle or video slot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"put":{"operationId":"configureBundleVideo","summary":"Configure a video slot","description":"Configures one slot as a video, carousel, or story, and schedules it. A story (TikTok/Instagram only) is a single video OR a single image (provide exactly one of video_url or story_image_url), has no description, and is verified by an account-manager screenshot. Platform-specific fields are only stored on their own platform: `tiktok_sound_url` on TikTok, every `instagram_*` field on Instagram, every `youtube_*` field on YouTube. A field belonging to another platform is accepted and not stored, but it is no longer discarded in silence: the response lists those names in `ignored_fields`, next to `platform`, with an `ignored_fields_note` explaining why. Check `ignored_fields` on every 200 — an empty or absent list is the only proof that everything you sent landed. Some options are paid and charged the first time they are set, never refunded: story_repost_url, instant_repost_as_story, and setting either volume field. Scheduling: `target_publish_date` is the FIRST day of a 2-day publishing window, never a fixed date — the end day is derived as that day + 1 and cannot be chosen, so `target_publish_end_date` is refused here with a hint pointing at PATCH. The window that was actually stored comes back as `target_publish_start_date` / `target_publish_end_date`. `auto_publish` is per-video HERE and top-level-only on the batch endpoint. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"position","in":"path","required":true,"description":"1-based video slot position.","schema":{"type":"integer","minimum":1}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureVideoRequest"}}}},"responses":{"200":{"description":"Configured video slot.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid video metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or video slot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Video status does not allow configuration. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"video_type\": \"video\",\n \"target_publish_date\": \"2026-06-01\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1', {\n method: 'PUT',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"video_type\": \"video\",\n \"target_publish_date\": \"2026-06-01\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PUT',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"video_type\\\": \\\"video\\\",\\n \\\"target_publish_date\\\": \\\"2026-06-01\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PUT\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1\", strings.NewReader(\"{\\n \\\"video_type\\\": \\\"video\\\",\\n \\\"target_publish_date\\\": \\\"2026-06-01\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]},"patch":{"operationId":"patchBundleVideo","summary":"Patch video metadata or schedule","description":"Changes a configured slot's name, description, external reference or schedule without re-sending its media. Rescheduling obeys the maximum of 3 videos per day per bundle AND — enforced since 2026-08-26, where before only the per-day cap ran — the same minimum publish lead time as configuration: today+1 with a delivered or existing account, today+3 while the account is still being created, in UTC. Today and any past date are rejected with `INVALID_DATE` carrying `min_days_ahead` and `earliest_allowed` (YYYY-MM-DD), the same shape the configure PUT returns. Send either target_publish_date (a 2-day window whose end is derived as that day + 1) or the target_publish_start_date/target_publish_end_date pair, never both — this is the ONLY endpoint where the window's end can be chosen, and it must fall strictly after the start. Cannot be used once the video is finalized. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"position","in":"path","required":true,"description":"1-based video slot position.","schema":{"type":"integer","minimum":1}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchVideoRequest"}}}},"responses":{"200":{"description":"Patched video slot.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid patch body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or video slot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Video status or account state does not allow this patch. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"external_ref\": \"external_ref\",\n \"name\": \"name\",\n \"description\": \"Campaign content description.\",\n \"target_publish_date\": \"2026-06-01\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"external_ref\": \"external_ref\",\n \"name\": \"name\",\n \"description\": \"Campaign content description.\",\n \"target_publish_date\": \"2026-06-01\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"external_ref\\\": \\\"external_ref\\\",\\n \\\"name\\\": \\\"name\\\",\\n \\\"description\\\": \\\"Campaign content description.\\\",\\n \\\"target_publish_date\\\": \\\"2026-06-01\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1\", strings.NewReader(\"{\\n \\\"external_ref\\\": \\\"external_ref\\\",\\n \\\"name\\\": \\\"name\\\",\\n \\\"description\\\": \\\"Campaign content description.\\\",\\n \\\"target_publish_date\\\": \\\"2026-06-01\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/batch":{"put":{"operationId":"batchConfigureBundleVideos","summary":"Configure video slots in bulk","description":"Configures many video slots in one call after a single account-level Coverage preflight. Partial success: this call returns HTTP 200 even when some or all rows are rejected. Read `configured`, `results` and `errors[]` and never infer success from the status code — rows breaking the 3-videos-per-day cap or the minimum lead time fail individually while the rest succeed, and the paid options they carry are only charged for the rows that succeeded. An `auto_publish` failure never fails the request; inspect `auto_publish.blockers`. TOP-LEVEL ONLY on this endpoint: one publish attempt per call, applying to every video in it. auto_publish inside videos[] is rejected with a hint telling you to move it out — it is per-video only on the single-slot PUT /bundles/{id}/videos/{position}. Each row's `target_publish_date` is the first day of a 2-day window whose end is derived (that day + 1); `target_publish_end_date` is refused on this endpoint. Publish-time date guard: any slot whose target date has already reached today or the past is moved forward to the earliest allowed day (today+1 with a delivered or existing account, today+3 while the account is still being created, in UTC), respecting the 3-videos-per-day-per-bundle cap — an overflowing day spills to the next one. Slots still in the future are NOT moved. This never fails the publish. When something moved, the response carries `adjusted_videos` — one entry per moved slot, `{video_id, position, previous_date, new_date}` — and `adjusted_videos_note`. Read them back instead of assuming the schedule you sent survived. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchConfigureVideosRequest"}}}},"responses":{"200":{"description":"Batch video configuration result.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid batch body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"One or more video slots or the account state does not allow configuration. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/batch\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"videos\": [\n {\n \"video_type\": \"video\",\n \"target_publish_date\": \"2026-06-01\",\n \"position\": 1\n }\n ]\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/batch', {\n method: 'PUT',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"videos\": [\n {\n \"video_type\": \"video\",\n \"target_publish_date\": \"2026-06-01\",\n \"position\": 1\n }\n ]\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PUT',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/batch',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"videos\\\": [\\n {\\n \\\"video_type\\\": \\\"video\\\",\\n \\\"target_publish_date\\\": \\\"2026-06-01\\\",\\n \\\"position\\\": 1\\n }\\n ]\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PUT\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/batch\", strings.NewReader(\"{\\n \\\"videos\\\": [\\n {\\n \\\"video_type\\\": \\\"video\\\",\\n \\\"target_publish_date\\\": \\\"2026-06-01\\\",\\n \\\"position\\\": 1\\n }\\n ]\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/publish-all":{"post":{"operationId":"publishAllBundleVideos","summary":"Publish all configured videos on an active bundle","description":"Hands every configured, unpublished slot on an active bundle to the account manager for posting. Publishing is irreversible once a manager has posted; call unscheduleBundleVideo beforehand to hold a slot back. Slots whose target date has already reached today or the past are moved forward to the earliest allowed day, respecting the 3-videos-per-day-per-bundle cap (an overflowing day spills to the next); slots still in the future are left alone, and the publish never fails because of it. When something moved, the response carries `dates_adjusted` (how many), `adjusted_videos` (one `{video_id, position, previous_date, new_date}` per moved slot) and `hint`. There is no `earliest_allowed_date` field on this response — it was documented but never returned, and `adjusted_videos` replaces it with the per-slot dates. Read them back instead of assuming the original schedule survived. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Published video slots.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Bundle status does not allow publishing videos. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/publish-all\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/publish-all', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/publish-all',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/publish-all\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/import-csv":{"post":{"operationId":"importBundleVideosCsv","summary":"Import video slots from CSV","description":"Uploads a CSV file, downloads the referenced media, and configures the available video slots. Partial success: this call returns HTTP 200 even when some or all rows are rejected. Read `imported`, `results` and `errors[]` and never infer success from the status code — rows breaking the 3-videos-per-day cap or the minimum lead time fail individually while the rest succeed. An `auto_publish` failure never fails the request; inspect `auto_publish.blockers`, and `auto_publish.adjusted_videos` when a stale date was moved forward at publish time. The date column is `target_publish_start_date` (note the name: the JSON endpoints call the same value `target_publish_date`) and it is the FIRST day of a 2-day window — the end is derived as that day + 1, so a `target_publish_end_date` column is refused with CSV_PARSE_ERROR rather than dropped. `auto_publish` is a form field on the multipart body and covers the whole import. Coverage is checked before TokPortal fetches or stores any referenced media. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"},"auto_publish":{"type":"boolean","default":false,"description":"Publish the bundle once the import has configured at least one row. Covers the whole import — there is one publish attempt per call. A publish failure never fails the import: read auto_publish.published, auto_publish.blockers and auto_publish.adjusted_videos."}}}}}},"responses":{"200":{"description":"CSV import result.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid CSV or upload body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"The account or bundle state does not allow CSV import. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/import-csv\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -F \"file=@/path/to/file\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/import-csv', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/import-csv',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/import-csv\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/{position}/publish":{"post":{"operationId":"publishBundleVideo","summary":"Publish one video slot","description":"Hands one configured slot to the account manager for posting on its target date. Irreversible once the manager has posted. If that target date has already reached today or the past it is moved forward to the earliest allowed day rather than published as instantly-due work, and the response then carries `date_adjusted: true`, `original_date`, `new_date` (both YYYY-MM-DD) and `hint`. Those four fields were documented long before they were real: until 2026-08-26 the RPC never returned them, and the slot published on its stale date. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"position","in":"path","required":true,"description":"1-based video slot position.","schema":{"type":"integer","minimum":1}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Video slot published.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or video slot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Bundle or video status does not allow publishing. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/publish\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/publish', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/publish',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/publish\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/{position}/reset":{"post":{"operationId":"resetBundleVideo","summary":"Reset one video slot","description":"Clears a slot's configuration so it can be configured again. Only works from `pending` or `configured`: to clear a published or accepted slot call unscheduleBundleVideo first, then reset. The slot's credits are not refunded and any paid option already charged on it stays charged. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"position","in":"path","required":true,"description":"1-based video slot position.","schema":{"type":"integer","minimum":1}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Video slot reset.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or video slot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Video status does not allow reset. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/reset\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/reset', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/reset',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/reset\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/{position}/unschedule":{"post":{"operationId":"unscheduleBundleVideo","summary":"Unschedule one video slot","description":"Pulls a published slot back out of the account-manager queue and returns it to `configured`, so it can be rescheduled or reset. Does not refund the slot. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"position","in":"path","required":true,"description":"1-based video slot position.","schema":{"type":"integer","minimum":1}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Video slot unscheduled.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or video slot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Video status does not allow unscheduling. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/unschedule\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/unschedule', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/unschedule',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/unschedule\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/{position}/finalize":{"post":{"operationId":"finalizeBundleVideo","summary":"Finalize video review","description":"Approves a delivered video and releases the account manager's payout — the review window cannot be reopened afterwards. Only valid while the slot is `in_review`. Any slot left in review is auto-finalized about 72 hours after entering it, so act inside that window. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"position","in":"path","required":true,"description":"1-based video slot position.","schema":{"type":"integer","minimum":1}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Video slot finalized.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or video slot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Video is not in review. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/finalize\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/finalize', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/finalize',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/finalize\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/{position}/corrections":{"post":{"operationId":"requestBundleVideoCorrections","summary":"Request video corrections","description":"Sends a delivered video back to the account manager with written feedback instead of approving it. Only valid while the slot is `in_review`, i.e. inside the ~72-hour window before it auto-finalizes. The response does not echo `fields`, so keep your own record of what you flagged. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"position","in":"path","required":true,"description":"1-based video slot position.","schema":{"type":"integer","minimum":1}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VideoCorrectionsRequest"}}}},"responses":{"200":{"description":"Video corrections requested.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid correction body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or video slot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Video is not in review. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/corrections\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"comment\": \"Please review this item.\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/corrections', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"comment\": \"Please review this item.\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/corrections',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"comment\\\": \\\"Please review this item.\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/corrections\", strings.NewReader(\"{\\n \\\"comment\\\": \\\"Please review this item.\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/videos/{position}/fix-download":{"post":{"operationId":"fixBundleVideoDownload","summary":"Fix a broken video download","description":"Replaces a manager-flagged broken video or carousel download URL and clears the download-issue flag. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"position","in":"path","required":true,"description":"1-based video slot position.","schema":{"type":"integer","minimum":1}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FixVideoDownloadRequest"}}}},"responses":{"200":{"description":"Video download issue fixed.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid replacement media body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle or video slot not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Video does not have a download issue. If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/fix-download\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"video_url\": \"https://example.com/resource\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/fix-download', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"video_url\": \"https://example.com/resource\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/fix-download',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"video_url\\\": \\\"https://example.com/resource\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/videos/1/fix-download\", strings.NewReader(\"{\\n \\\"video_url\\\": \\\"https://example.com/resource\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts":{"get":{"operationId":"listAccounts","summary":"List delivered accounts","description":"Lists delivered saved accounts (real accounts that exist on the platform). Note the product has two ids: the account *listing* id carried by a bundle is stable across remakes, while the `saved_account_id` returned here is replaced every time an account is remade.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"platform","in":"query","required":false,"description":"Filter by platform.","schema":{"type":"string","enum":["tiktok","instagram"]}},{"name":"country","in":"query","required":false,"description":"Filter by country code or country alias.","schema":{"type":"string"}},{"name":"banned","in":"query","required":false,"description":"Filter by ban state. true returns only banned accounts (staff-validated or park-scan detected, matching the `banned` response field); false returns only non-banned accounts.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Paginated delivered account list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountListResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/accounts?page=example&per_page=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts?page=example&per_page=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/accounts?page=example&per_page=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/accounts?page=example&per_page=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/account-bans":{"get":{"operationId":"listAccountBans","summary":"List ban reports and appeals","description":"Pollable list of validated ban reports for the caller's delivered accounts, covering the whole lifecycle: appeal_pending (platform appeal filed, account unavailable but NOT yet banned), appeal_accepted (account survived), appeal_refused / no_appeal_banned (confirmed ban), and the staff commercial resolution (refund / remake / no_remake with a machine-readable reason_code such as tos_ban). While a report is appeal_pending, do NOT order a replacement account: a duplicate can trigger a ban-evasion strike on the platform, which is why TokPortal itself waits for the appeal. Key your reports on bundle_id — account_id can be null after a staff reset. A resolution of refund returns setup, warming and unused video slots, but not work already delivered and not the Coverage period, and the restored credits expire 60 days after restoration (see the credits.restored event in listWebhookEvents). This is the REST counterpart of the account.banned, account.ban_appeal.submitted, account.ban_appeal.resolved and account.ban_resolution.decided webhook events. Only staff/CM-validated bans appear here — detections from TokPortal's internal health scan are never listed. Poll with the since parameter (updated_at watermark) to pick up new reports and status changes.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","required":false,"description":"Filter by appeal lifecycle status.","schema":{"type":"string","enum":["appeal_pending","appeal_accepted","appeal_refused","no_appeal_banned"]}},{"name":"resolution","in":"query","required":false,"description":"Filter by staff commercial resolution. 'pending' selects confirmed bans still awaiting the staff decision.","schema":{"type":"string","enum":["refund","remake","no_remake","pending"]}},{"name":"account_id","in":"query","required":false,"description":"Filter by saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"since","in":"query","required":false,"description":"Only reports updated at or after this ISO 8601 timestamp. Use the highest updated_at you have seen as a polling watermark.","schema":{"type":"string","format":"date-time"}},{"name":"include_screenshots","in":"query","required":false,"description":"When true, each report includes a signed 7-day URL of the ban-evidence screenshot when one exists.","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Paginated ban report list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountBanListResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/account-bans?page=example&per_page=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/account-bans?page=example&per_page=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/account-bans?page=example&per_page=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/account-bans?page=example&per_page=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}":{"get":{"operationId":"getAccount","summary":"Get a delivered account","description":"Returns one delivered account: handle, platform, Coverage state, ban state and warming summary. A `saved_account_id` invalidated by a remake returns 404 — re-read the bundle to get the new one.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Delivered account details. For an eligible TikTok or Instagram account created before the global Coverage cutoff, managed_subscription is null because the account is grandfathered. It can also be null for an ineligible platform or when no Coverage record exists. Otherwise, this stable technical TokPortal Coverage field contains the one per-saved-account status, period, unpaid periods, task access and reactivation price.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/commenting-profile":{"patch":{"operationId":"updateAccountCommentingProfile","summary":"Update account commenting profile","description":"Sets the internal commenting-autopilot metadata (niche, persona, goal, language, tracked handles) that TokPortal uses to draft comments for this account. It NEVER changes the account's public profile — use createAccountEditRequest to change a delivered account's username, visible name, biography, picture or link. The account must belong to the API key owner and must have active TokPortal Coverage, unless it is permanently grandfathered. Revealed/detached, banned, paused, lapsed and unrecoverable accounts are read-only.","tags":["Accounts","Comments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountCommentingProfileRequest"}}}},"responses":{"200":{"description":"Updated account commenting profile.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid commenting profile body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Account mutation blocked. Inspect error.details.reason; reactivate TokPortal Coverage when the state is recoverable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/commenting-profile\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"niche\": \"niche\",\n \"persona\": \"persona\",\n \"goal\": \"promotion\",\n \"language\": \"language\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/commenting-profile', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"niche\": \"niche\",\n \"persona\": \"persona\",\n \"goal\": \"promotion\",\n \"language\": \"language\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/commenting-profile',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"niche\\\": \\\"niche\\\",\\n \\\"persona\\\": \\\"persona\\\",\\n \\\"goal\\\": \\\"promotion\\\",\\n \\\"language\\\": \\\"language\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/commenting-profile\", strings.NewReader(\"{\\n \\\"niche\\\": \\\"niche\\\",\\n \\\"persona\\\": \\\"persona\\\",\\n \\\"goal\\\": \\\"promotion\\\",\\n \\\"language\\\": \\\"language\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/bundles":{"get":{"operationId":"listAccountBundles","summary":"List bundles for a delivered account","description":"Lists every bundle attached to one delivered account, including cancelled ones. Use it to see an account's full order history before ordering more work on it.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","required":false,"description":"Filter by bundle status.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated bundles for account.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/bundles?page=example&per_page=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/bundles?page=example&per_page=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/bundles?page=example&per_page=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/bundles?page=example&per_page=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/verification-code":{"post":{"operationId":"retrieveAccountVerificationCode","summary":"Retrieve latest account verification code","description":"Retrieving a verification code is the same irreversible first-access event as revealing credentials. Its policy is determined by this saved account's created_at timestamp against the immutable managed_pricing_new_customer_cutover_at value, never by the workspace action-pricing cohort or August 14 grace deadline. A saved account created before the cutoff permanently keeps the prior API contract: 0 credits, no new versioned acknowledgment body required, no TokPortal detachment, existing task access remains available, and support plus ban coverage end after access. A saved account created at or after the cutoff follows the managed policy: normally 150 credits, or the stored $10 legacy / $15 new per-30-day rate when Account Owning is already admin-approved. Managed access permanently detaches the account, makes it read-only, and ends TokPortal Coverage, task access, analytics updates, support, ban protection, replacement, refunds, compensation and credit restoration. For a new-policy account, missing explicit acceptance fails with 428 and returns the exact account-specific terms, price and policy version. A changed quote returns 409 before any debit or reveal. Reaching the Account Owning eligibility threshold only submits an admin review request; it never activates the agreement automatically. While approval is pending, reveal remains available for 150 credits on a post-cutoff account. Do not send Idempotency-Key: this response contains a verification secret and is never stored in the replay ledger. A request that includes the header is rejected before any ledger claim, reveal, debit, or inbox access with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400). After an uncertain transport result, fetch the safe account state before deciding whether to call this endpoint again without the header.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcknowledgeSupportForfeitRequest"}}}},"responses":{"200":{"description":"Verification code result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationCodeResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Idempotency-Key is not supported because the response contains a verification secret. Remove the header and retry only after reconciling account state. Error code: IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits for the applicable one-time reveal, or incomplete activation or billing for an admin-approved Account Owning Fee agreement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Account or verification code not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"CREDENTIAL_REVEAL_QUOTE_CHANGED: the submitted non-empty policy version or approved price snapshot is stale. Nothing was charged or revealed. Show the current disclosure and exact expected_credit_cost returned in error.details, obtain fresh consent, then retry with details.policy_version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialRevealNegotiationErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"428":{"description":"CREDENTIALS_ACKNOWLEDGMENT_REQUIRED: acceptance or its policy version is missing. Nothing was charged or revealed. Show error.details to the account owner, obtain consent, then retry with acknowledge_support_forfeit=true and details.policy_version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialRevealNegotiationErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"reject-sensitive-response","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verification-code\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"acknowledge_support_forfeit\": true,\n \"policy_version\": \"VERSION_RETURNED_BY_428\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verification-code', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"acknowledge_support_forfeit\": true,\n \"policy_version\": \"VERSION_RETURNED_BY_428\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verification-code',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"acknowledge_support_forfeit\\\": true,\\n \\\"policy_version\\\": \\\"VERSION_RETURNED_BY_428\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verification-code\", strings.NewReader(\"{\\n \\\"acknowledge_support_forfeit\\\": true,\\n \\\"policy_version\\\": \\\"VERSION_RETURNED_BY_428\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/reveal-credentials":{"post":{"operationId":"revealAccountCredentials","summary":"Reveal delivered account credentials","description":"The first credential or verification-code access is priced from this saved account's created_at timestamp against the immutable managed_pricing_new_customer_cutover_at value, never from the workspace action-pricing cohort or August 14 grace deadline. A saved account created before the cutoff permanently keeps the prior API contract: the reveal costs 0 credits, requires no new versioned acknowledgment body, and is irreversible; support and ban coverage end, but the account is not detached and existing TokPortal task access remains available. A saved account created at or after the cutoff follows the managed policy and requires the explicit versioned acknowledgment handshake: normally 150 credits, or the stored $10 legacy / $15 new per-30-day rate when Account Owning is already admin-approved. Crossing the Account Owning eligibility threshold only submits an admin review request and never activates it automatically. While approval is pending, reveal remains available for 150 credits on a post-cutoff account. Under the managed policy the charge is final and non-refundable, and reveal permanently detaches the account, makes it read-only, and ends TokPortal Coverage, all task access, analytics updates, support, ban protection, replacement, refunds, compensation and credit restoration. TokPortal is not responsible for later access, performance, reach, security, restrictions or bans. The debit or Account Owning activation, reveal marker and Coverage shutdown commit atomically. Previously revealed accounts are not charged a second time. Do not send Idempotency-Key: this response contains credentials and is never stored in the replay ledger. A request that includes the header is rejected before any ledger claim, reveal, debit, or secret access with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400). After an uncertain transport result, fetch the safe account state before deciding whether to call this endpoint again without the header.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcknowledgeSupportForfeitRequest"}}}},"responses":{"200":{"description":"Credentials reveal result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevealCredentialsResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Idempotency-Key is not supported because the response contains credentials. Remove the header and retry only after reconciling account state. Error code: IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits for the applicable one-time reveal, or incomplete activation or billing for an admin-approved Account Owning Fee agreement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"CREDENTIAL_REVEAL_QUOTE_CHANGED: the submitted non-empty policy version or approved price snapshot is stale. Nothing was charged or revealed. Show the current disclosure and exact expected_credit_cost returned in error.details, obtain fresh consent, then retry with details.policy_version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialRevealNegotiationErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"428":{"description":"CREDENTIALS_ACKNOWLEDGMENT_REQUIRED: acceptance or its policy version is missing. Nothing was charged or revealed. Show error.details to the account owner, obtain consent, then retry with acknowledge_support_forfeit=true and details.policy_version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialRevealNegotiationErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"reject-sensitive-response","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/reveal-credentials\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"acknowledge_support_forfeit\": true,\n \"policy_version\": \"VERSION_RETURNED_BY_428\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/reveal-credentials', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"acknowledge_support_forfeit\": true,\n \"policy_version\": \"VERSION_RETURNED_BY_428\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/reveal-credentials',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"acknowledge_support_forfeit\\\": true,\\n \\\"policy_version\\\": \\\"VERSION_RETURNED_BY_428\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/reveal-credentials\", strings.NewReader(\"{\\n \\\"acknowledge_support_forfeit\\\": true,\\n \\\"policy_version\\\": \\\"VERSION_RETURNED_BY_428\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/analytics/can-refresh":{"get":{"operationId":"canRefreshAccountAnalytics","summary":"Check analytics refresh availability","description":"Reports whether a manual analytics refresh is currently allowed and when the next one will be. Call it before refreshAccountAnalytics / refreshAnalyticsAccount to avoid a 429 cooldown (6 h for connected accounts, 24 h for the public fallback).","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Manual refresh availability. can_refresh is false and reason identifies the Coverage or analytics-plan blocker when refresh is unavailable.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/can-refresh\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/can-refresh', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/can-refresh',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/can-refresh\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/analytics/refresh":{"post":{"operationId":"refreshAccountAnalytics","summary":"Refresh account analytics","description":"Legacy account-analytics refresh path, kept for older integrations; new code should call refreshAnalyticsAccount. Comment collection is gated on three conditions: includeComments only runs when force is true, includePosts is not false, and the workspace holds the full analytics tier. The two you control are refusals, not silence — includeComments without force, or with includePosts false, fails with INVALID_FIELD for MCP callers and is reported for direct REST callers. The one you cannot control, the analytics tier, comes back on the response as applied.include_comments plus applied.include_comments_dropped_reason. The call can still return 200 with deduped: true and skippedReason: \"recent_snapshot\", which means nothing was refreshed. Check canRefreshAccountAnalytics first: a forced retry consumes the manual-refresh cooldown slot and the next one is rejected with 429. Refresh is blocked for revealed/detached, banned or inactive-Coverage accounts; permanently grandfathered accounts remain eligible.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshAnalyticsRequest"}}}},"responses":{"200":{"description":"Refresh result.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"Plan does not include this analytics level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Account refresh blocked. The response reason identifies the account or TokPortal Coverage state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Manual refresh cooldown active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"502":{"description":"Refresh provider failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/refresh\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"force\": false,\n \"includePosts\": false,\n \"includeComments\": false,\n \"forcePosts\": false\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/refresh', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"force\": false,\n \"includePosts\": false,\n \"includeComments\": false,\n \"forcePosts\": false\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/refresh',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"force\\\": false,\\n \\\"includePosts\\\": false,\\n \\\"includeComments\\\": false,\\n \\\"forcePosts\\\": false\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/refresh\", strings.NewReader(\"{\\n \\\"force\\\": false,\\n \\\"includePosts\\\": false,\\n \\\"includeComments\\\": false,\\n \\\"forcePosts\\\": false\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/edit-request":{"get":{"operationId":"getAccountEditRequest","summary":"Get active account edit request","description":"Returns the account's profile edit requests, newest first, with their status and credit cost. Only one request can be open per account at a time, so check here before calling createAccountEditRequest.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Active edit request.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/edit-request\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/edit-request', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/edit-request',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/edit-request\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"post":{"operationId":"createAccountEditRequest","summary":"Request profile edits for a delivered account","description":"Requests profile changes on an account that is already delivered and debits 8 credits. This is the ONLY way to change a delivered account's public username, visible name, biography, picture or link-in-bio: addEditSlots is unrelated (it buys video-editing slots) and configureBundleAccount only works before the account is delivered. Besides the username and visible name, supply at least one of requested_biography, requested_profile_picture_url or requested_link_in_bio — a request that changes nothing else is rejected. Only one request can be open per account at a time (409 otherwise); check getAccountEditRequest first. Active TokPortal Coverage and a routable active account manager are required. TokPortal uses the account's current active manager, then its still-active manager relationship, then eligible non-cancelled order history. Completed bundles remain eligible without a delivery-age limit; cancelled orders are never restored. Assignment, debit, and task creation are atomic, so an unavailable manager never costs credits. The task appears directly in that manager's calendar.","tags":["Accounts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountEditRequest"}}}},"responses":{"201":{"description":"Edit request created.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid edit request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Coverage is inactive, no active account manager or non-cancelled support order is available, or an active edit request already exists. No credits are charged on these failures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/edit-request\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"requested_username\": \"requested_username\",\n \"requested_visible_name\": \"requested_visible_name\",\n \"requested_biography\": \"requested_biography\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/edit-request', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"requested_username\": \"requested_username\",\n \"requested_visible_name\": \"requested_visible_name\",\n \"requested_biography\": \"requested_biography\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/edit-request',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"requested_username\\\": \\\"requested_username\\\",\\n \\\"requested_visible_name\\\": \\\"requested_visible_name\\\",\\n \\\"requested_biography\\\": \\\"requested_biography\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/edit-request\", strings.NewReader(\"{\\n \\\"requested_username\\\": \\\"requested_username\\\",\\n \\\"requested_visible_name\\\": \\\"requested_visible_name\\\",\\n \\\"requested_biography\\\": \\\"requested_biography\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/rewarm":{"post":{"operationId":"rewarmAccount","summary":"Order Advanced Niche Warming (rewarm) on a delivered account","description":"Starts an Advanced Niche Warming session on a saved account that is already delivered: for each provided term the manager screen-records a session that opens on the account profile (handle visible), searches the term on the account's platform, watches videos from the results, engages with them (likes/saves) and leaves a comment. Every recording is verified before completion. The standard rate is 5 credits per term, charged per target and never per day (3-30 terms, multiples of 3), with a 15-credit minimum; GET /credit-costs returns the effective rate. Once the session has tasks it is NEVER refunded, so confirm the total with the user before calling. Call listAccountWarmingSessions first: only one session can be active per account and a second one is rejected with 409 REWARM_ALREADY_ACTIVE. Requires active TokPortal Coverage, a routable active account manager backed by a non-cancelled support order, TikTok or Instagram, and no already-active warming session. A completed bundle remains eligible. Terms are split evenly over 3 calendar days in the manager's timezone; earlier-day tasks remain available until completed and sessions with tasks do not expire.","tags":["Warming"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewarmAccountRequest"}}}},"responses":{"201":{"description":"Warming session created and started.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarmingSessionResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid terms (ADVANCED_WARMING_TERMS) or unsupported platform (ADVANCED_WARMING_PLATFORM).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"Account belongs to another user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"No routable active account manager or non-cancelled support order (legacy code REWARM_NO_ACTIVE_ORDER), Coverage is inactive, or a warming session is already active (REWARM_ALREADY_ACTIVE). No credits are charged on these failures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/rewarm\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"search_terms\": [\n \"search_terms 1\",\n \"search_terms 2\",\n \"search_terms 3\"\n ]\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/rewarm', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"search_terms\": [\n \"search_terms 1\",\n \"search_terms 2\",\n \"search_terms 3\"\n ]\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/rewarm',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"search_terms\\\": [\\n \\\"search_terms 1\\\",\\n \\\"search_terms 2\\\",\\n \\\"search_terms 3\\\"\\n ]\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/rewarm\", strings.NewReader(\"{\\n \\\"search_terms\\\": [\\n \\\"search_terms 1\\\",\\n \\\"search_terms 2\\\",\\n \\\"search_terms 3\\\"\\n ]\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/bundles/{id}/warming-terms":{"put":{"operationId":"configureBundleWarmingTerms","summary":"Configure the niche targets of a count-only Advanced Niche Warming purchase","description":"Only for a bundle created with advanced_warming_terms_count (deferred targets). To warm an account that is already delivered, use rewarmAccount instead; this endpoint answers 404 WARMING_SESSION_NOT_FOUND when there is no count-only purchase to configure. Must provide EXACTLY the purchased number of targets. One-shot: once configured the targets cannot be changed. Unlike PUT /bundles/{id}/account, this stays available at any account status after the manager accepted the mission or submitted the account, in which case the warming session starts immediately. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription. A new account that has not produced a saved account yet remains configurable before delivery.","tags":["Warming"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Bundle ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureWarmingTermsRequest"}}}},"responses":{"200":{"description":"Targets configured (started=true when the session began immediately).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarmingSessionResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Wrong number of targets or invalid targets (ADVANCED_WARMING_TERMS), or an unrecognised field in the body (UNKNOWN_FIELD).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found, or no warming session to configure (WARMING_SESSION_NOT_FOUND).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Targets already configured (WARMING_TERMS_ALREADY_SET). If error.code is MANAGED_ACCOUNT_TASK_BLOCKED, read error.details.account_id and error.details.reason, fetch GET /accounts/{account_id}/managed-subscription, and reactivate only when that state is recoverable before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/warming-terms\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"advanced_warming_terms\": [\n \"advanced_warming_terms 1\",\n \"advanced_warming_terms 2\",\n \"advanced_warming_terms 3\"\n ]\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/warming-terms', {\n method: 'PUT',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"advanced_warming_terms\": [\n \"advanced_warming_terms 1\",\n \"advanced_warming_terms 2\",\n \"advanced_warming_terms 3\"\n ]\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PUT',\n 'https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/warming-terms',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"advanced_warming_terms\\\": [\\n \\\"advanced_warming_terms 1\\\",\\n \\\"advanced_warming_terms 2\\\",\\n \\\"advanced_warming_terms 3\\\"\\n ]\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PUT\", \"https://app.tokportal.com/api/ext/bundles/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/warming-terms\", strings.NewReader(\"{\\n \\\"advanced_warming_terms\\\": [\\n \\\"advanced_warming_terms 1\\\",\\n \\\"advanced_warming_terms 2\\\",\\n \\\"advanced_warming_terms 3\\\"\\n ]\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/warming-sessions":{"get":{"operationId":"listAccountWarmingSessions","summary":"List Advanced Niche Warming sessions for an account","description":"Lists Advanced Niche Warming sessions (newest first) for a saved account you own, including per-term tasks, per-term reports, proof links, and the aggregated session report when completed. Tasks unlock over 3 calendar days in the manager's timezone and, once created, do not expire.","tags":["Warming"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Warming sessions with tasks and reports.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"Account belongs to another user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/warming-sessions\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/warming-sessions', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/warming-sessions',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/warming-sessions\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/warming-sessions/{id}":{"get":{"operationId":"getWarmingSession","summary":"Get an Advanced Niche Warming session","description":"Returns one Advanced Niche Warming session you own: status, per-term tasks (with 3-calendar-day dispatch in the manager's timezone, verification status, client report and proof video link), and the aggregated report on completion. Created tasks remain open until completed; they do not expire.","tags":["Warming"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Warming session ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Warming session detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarmingSessionResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Warming session not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/warming-sessions/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/warming-sessions/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/warming-sessions/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/warming-sessions/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/warming/generate-terms":{"post":{"operationId":"generateWarmingTerms","summary":"Generate Advanced Niche Warming search terms","description":"Generates platform-appropriate Advanced Niche Warming search terms (niche targets) from a free-text niche description (max 1000 characters). This is free and no credits are charged. Call it before buying warming rather than inventing terms: pass the result to advanced_warming_terms (bundle creation or PUT /bundles/{id}/warming-terms deferred configuration) or to search_terms (rewarmAccount).","tags":["Warming"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateWarmingTermsRequest"}}}},"responses":{"200":{"description":"Generated search terms.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid count/description (ADVANCED_WARMING_TERMS) or unsupported platform (ADVANCED_WARMING_PLATFORM).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"502":{"description":"Term generation failed (TERM_GENERATION_FAILED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI generation unavailable (AI_UNAVAILABLE).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/warming/generate-terms\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"text\": \"text\",\n \"platform\": \"tiktok\",\n \"count\": 27\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/warming/generate-terms', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"text\": \"text\",\n \"platform\": \"tiktok\",\n \"count\": 27\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/warming/generate-terms',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"text\\\": \\\"text\\\",\\n \\\"platform\\\": \\\"tiktok\\\",\\n \\\"count\\\": 27\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/warming/generate-terms\", strings.NewReader(\"{\\n \\\"text\\\": \\\"text\\\",\\n \\\"platform\\\": \\\"tiktok\\\",\\n \\\"count\\\": 27\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/webhooks/events":{"get":{"operationId":"listWebhookEvents","summary":"List webhook event catalog","description":"Returns the supported webhook event types with, for each one, its description, exact trigger condition, payload schema and an example payload, plus the delivery envelope and signature scheme. Read it before subscribing: several names are counter-intuitive — account.published fires when you publish the order, not when the account is delivered (that is account.in_review), and warming.session_started is not emitted for warming whose terms were set at bundle creation. This endpoint is public so teams can inspect webhook contracts before creating an API key.","tags":["Webhooks"],"security":[],"responses":{"200":{"description":"Supported webhook events and delivery contract.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventsResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/webhooks/events\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/webhooks/events', {\n method: 'GET',\n headers: {\n \n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/webhooks/events',\n headers={}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/webhooks/events\", nil)\nresp, err := http.DefaultClient.Do(req)"}]}},"/webhooks":{"get":{"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","description":"Lists your webhook endpoints with their subscribed events and enabled state. Signing secrets are never returned here — only once, at creation.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"enabled","in":"query","required":false,"description":"Filter by enabled state.","schema":{"type":"boolean"}},{"name":"event","in":"query","required":false,"description":"Filter endpoints subscribed to an event.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated webhook endpoint list.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/webhooks?page=example&per_page=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/webhooks?page=example&per_page=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/webhooks?page=example&per_page=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/webhooks?page=example&per_page=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"post":{"operationId":"createWebhookEndpoint","summary":"Create a webhook endpoint","description":"Creates a webhook endpoint and returns its signing secret once — store it, because a lost secret can only be replaced by deleting the endpoint and creating a new one. Call listWebhookEvents before choosing `events`: it returns the description, trigger condition and payload schema of each event, and several names are counter-intuitive. In particular account.published fires when YOU publish the order, not when the account is delivered — the delivery signal is account.in_review, and account.finalized fires when the account review is approved. Do not send Idempotency-Key. The successful response contains a secret and is never stored in the replay ledger. A request with the header is rejected with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400) before any ledger claim or operation execution.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"}}}},"responses":{"201":{"description":"Webhook endpoint created.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid webhook endpoint. Idempotency-Key is not supported because the successful response contains a secret. Remove the header before retrying. Error code: IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Endpoint already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"reject-sensitive-response","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/webhooks\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://example.com/resource\",\n \"events\": [\n \"webhook.test\"\n ]\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/webhooks', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"url\": \"https://example.com/resource\",\n \"events\": [\n \"webhook.test\"\n ]\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/webhooks',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"url\\\": \\\"https://example.com/resource\\\",\\n \\\"events\\\": [\\n \\\"webhook.test\\\"\\n ]\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/webhooks\", strings.NewReader(\"{\\n \\\"url\\\": \\\"https://example.com/resource\\\",\\n \\\"events\\\": [\\n \\\"webhook.test\\\"\\n ]\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/webhooks/{id}":{"get":{"operationId":"getWebhookEndpoint","summary":"Get a webhook endpoint","description":"Returns one webhook endpoint's URL, subscribed events and enabled state. The signing secret is not returned; if you lost it, delete this endpoint and create a replacement.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Webhook endpoint details.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Webhook endpoint not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"patch":{"operationId":"updateWebhookEndpoint","summary":"Update a webhook endpoint","description":"Changes an endpoint's URL, subscribed events, description or enabled state. The signing secret is unchanged and is never re-returned. Call listWebhookEvents for the meaning, trigger condition and payload of each event type before changing the subscription list.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookEndpointRequest"}}}},"responses":{"200":{"description":"Webhook endpoint updated.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid webhook endpoint patch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Webhook endpoint not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://example.com/resource\",\n \"events\": [\n \"webhook.test\"\n ],\n \"description\": \"Campaign content description.\",\n \"enabled\": false\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"url\": \"https://example.com/resource\",\n \"events\": [\n \"webhook.test\"\n ],\n \"description\": \"Campaign content description.\",\n \"enabled\": false\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"url\\\": \\\"https://example.com/resource\\\",\\n \\\"events\\\": [\\n \\\"webhook.test\\\"\\n ],\\n \\\"description\\\": \\\"Campaign content description.\\\",\\n \\\"enabled\\\": false\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", strings.NewReader(\"{\\n \\\"url\\\": \\\"https://example.com/resource\\\",\\n \\\"events\\\": [\\n \\\"webhook.test\\\"\\n ],\\n \\\"description\\\": \\\"Campaign content description.\\\",\\n \\\"enabled\\\": false\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]},"delete":{"operationId":"deleteWebhookEndpoint","summary":"Delete a webhook endpoint","description":"Permanently deletes a webhook endpoint and invalidates its signing secret. Events that could not be delivered are not queued for a replacement endpoint.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"204":{"description":"Webhook endpoint deleted.","headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Webhook endpoint not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'DELETE',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'DELETE',\n 'https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"DELETE\", \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/webhooks/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List webhook deliveries","description":"Lists delivery attempts for one endpoint with the response status and body. Deliveries are at-least-once and retries reuse the same `TokPortal-Event-Id` — deduplicate on that id, not on the delivery id.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID.","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"event_type","in":"query","required":false,"description":"Filter by event type.","schema":{"type":"string"}},{"name":"success","in":"query","required":false,"description":"Filter by delivery success.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Paginated delivery attempts for the webhook endpoint.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Webhook endpoint not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/deliveries?page=example&per_page=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/deliveries?page=example&per_page=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/deliveries?page=example&per_page=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/deliveries?page=example&per_page=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/webhooks/{id}/deliveries/{delivery_id}/retry":{"post":{"operationId":"retryWebhookDelivery","summary":"Retry a webhook delivery","description":"Resends the stored webhook payload to the endpoint's current URL with a fresh TokPortal-Signature header. The event ID is preserved so receivers can keep idempotent processing.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID.","schema":{"type":"string","format":"uuid"}},{"name":"delivery_id","in":"path","required":true,"description":"Webhook delivery ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Retry delivery result.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Webhook endpoint or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Webhook endpoint is disabled or payload is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/deliveries/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/retry\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/deliveries/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/retry', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/deliveries/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/retry',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/deliveries/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/retry\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/webhooks/{id}/test":{"post":{"operationId":"testWebhookEndpoint","summary":"Send a test webhook","description":"Sends a signed webhook.test event to the endpoint and records the delivery result.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Test delivery result.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Webhook endpoint not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/test\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/test', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/test',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/webhooks/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/test\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/upload/video":{"post":{"operationId":"uploadVideo","summary":"Create a video upload URL","description":"Returns a short-lived presigned upload capability for a video file. The `public_url` it returns is what goes into `video_url` on configureBundleVideo — images are the opposite and require the upload response's `storage_path`. Do not send Idempotency-Key. The successful response contains a secret and is never stored in the replay ledger. A request with the header is rejected with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400) before any ledger claim or operation execution.","tags":["Uploads"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadVideoRequest"}}}},"responses":{"200":{"description":"Presigned video upload URL.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid upload request. Idempotency-Key is not supported because the successful response contains a secret. Remove the header before retrying. Error code: IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"reject-sensitive-response","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/upload/video\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"media.mp4\",\n \"bundle_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/upload/video', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"filename\": \"media.mp4\",\n \"bundle_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/upload/video',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"filename\\\": \\\"media.mp4\\\",\\n \\\"bundle_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/upload/video\", strings.NewReader(\"{\\n \\\"filename\\\": \\\"media.mp4\\\",\\n \\\"bundle_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/upload/video/direct":{"post":{"operationId":"uploadVideoDirect","summary":"Upload a video file directly","description":"Uploads multipart/form-data directly through TokPortal and returns the public video URL, which goes straight into `video_url` on configureBundleVideo.","tags":["Uploads"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","bundle_id"],"properties":{"file":{"type":"string","format":"binary"},"bundle_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Uploaded video URL.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid upload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/upload/video/direct\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -F \"file=@/path/to/file\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/upload/video/direct', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/upload/video/direct',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/upload/video/direct\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/upload/image":{"post":{"operationId":"uploadImage","summary":"Create an image upload URL","description":"Returns a short-lived signed upload URL and upload token for an image. Use the returned `storage_path` — NOT `public_url` — for `carousel_images` and `profile_picture_url`; videos are the opposite, uploadVideo returns a `public_url` that goes straight into `video_url`. The stored object's extension comes from the declared `content_type` (image/png stores a .png), and only falls back to the extension in `filename` when the content type is unknown, so send the content type that matches the bytes you are about to PUT. `storage_path` on the response is the key the object is actually stored under — read it rather than rebuilding it from `filename`. Do not send Idempotency-Key. The successful response contains a secret and is never stored in the replay ledger. A request with the header is rejected with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400) before any ledger claim or operation execution.","tags":["Uploads"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadImageRequest"}}}},"responses":{"200":{"description":"Signed image upload URL.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid upload request. Idempotency-Key is not supported because the successful response contains a secret. Remove the header before retrying. Error code: IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"reject-sensitive-response","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/upload/image\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"profile.png\",\n \"content_type\": \"image/png\",\n \"bundle_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/upload/image', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"filename\": \"profile.png\",\n \"content_type\": \"image/png\",\n \"bundle_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/upload/image',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"filename\\\": \\\"profile.png\\\",\\n \\\"content_type\\\": \\\"image/png\\\",\\n \\\"bundle_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/upload/image\", strings.NewReader(\"{\\n \\\"filename\\\": \\\"profile.png\\\",\\n \\\"content_type\\\": \\\"image/png\\\",\\n \\\"bundle_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/upload/image/direct":{"post":{"operationId":"uploadImageDirect","summary":"Upload an image file directly","description":"Uploads multipart/form-data directly through TokPortal and returns storage details. Use the returned `storage_path` — NOT `public_url` — for `carousel_images` and `profile_picture_url`. HEIF/HEIC may be converted to JPEG. `purpose` is validated like it is on the JSON upload endpoints: an explicit value other than `carousel` or `profile_picture` is refused with INVALID_FIELD for MCP callers and reported in `meta.ignored_fields` for direct REST callers — it is no longer quietly rounded down to `carousel`. Omitting `purpose` still means `carousel`, which is the documented default. Confirm the destination with the returned `bucket`.","tags":["Uploads"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","bundle_id"],"properties":{"file":{"type":"string","format":"binary"},"bundle_id":{"type":"string","format":"uuid"},"purpose":{"type":"string","enum":["carousel","profile_picture"],"default":"carousel"}}}}}},"responses":{"200":{"description":"Uploaded image URL.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid upload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/upload/image/direct\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -F \"file=@/path/to/file\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/upload/image/direct', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/upload/image/direct',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/upload/image/direct\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/upload/image/from-url":{"post":{"operationId":"uploadImageFromUrl","summary":"Import an image from URL","description":"Fetches a public direct image URL and stores it permanently in TokPortal storage. Use the returned `storage_path` — NOT `public_url` — for `carousel_images` and `profile_picture_url`.","tags":["Uploads"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadImageFromUrlRequest"}}}},"responses":{"200":{"description":"Stored image details.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid image URL or request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Bundle not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/upload/image/from-url\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://example.com/resource\",\n \"bundle_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/upload/image/from-url', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"url\": \"https://example.com/resource\",\n \"bundle_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/upload/image/from-url',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"url\\\": \\\"https://example.com/resource\\\",\\n \\\"bundle_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/upload/image/from-url\", strings.NewReader(\"{\\n \\\"url\\\": \\\"https://example.com/resource\\\",\\n \\\"bundle_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics":{"get":{"operationId":"getAnalyticsDashboard","summary":"Get analytics dashboard","description":"Portfolio-level analytics across your accounts for a date range. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"workspace","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"platform","in":"query","required":false,"description":"Repeatable platform filter.","schema":{"type":"string","enum":["tiktok","instagram"]}},{"name":"country","in":"query","required":false,"description":"Repeatable country filter.","schema":{"type":"string"}},{"name":"account","in":"query","required":false,"description":"Repeatable account filter.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Analytics dashboard data.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/analytics?workspace=example&platform=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics?workspace=example&platform=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/analytics?workspace=example&platform=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/analytics?workspace=example&platform=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/contract":{"get":{"operationId":"getAnalyticsContract","summary":"Get analytics data contract","description":"Returns the Analytics v2 contract, current access payload, metric semantics, freshness targets, and redaction rules.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Analytics contract and access payload.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/analytics/contract\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/contract', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/analytics/contract',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/analytics/contract\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/export/videos":{"get":{"operationId":"exportAnalyticsVideos","summary":"Export analytics videos CSV","description":"CSV export of post-level analytics for the selected accounts and date range. Requires the Creator tier or above. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"account","in":"query","required":false,"description":"Repeatable account filter.","schema":{"type":"string"}},{"name":"workspace","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"platform","in":"query","required":false,"description":"Repeatable platform filter.","schema":{"type":"string","enum":["tiktok","instagram"]}},{"name":"country","in":"query","required":false,"description":"Repeatable country filter.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Search query.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"CSV export of analytics video rows.","content":{"text/csv":{"schema":{"type":"string"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"Plan does not include this analytics level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/analytics/export/videos?account=example&workspace=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/export/videos?account=example&workspace=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/analytics/export/videos?account=example&workspace=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/analytics/export/videos?account=example&workspace=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/export/reports":{"post":{"operationId":"createAnalyticsReport","summary":"Create analytics web report","description":"Creates a shareable Analytics v2 web report and returns its bearer-like access token and URL. The body is validated before anything is rendered, so a malformed request fails with INVALID_FIELD instead of quietly producing a wrong report for your end client. `from` and `to` are calendar dates in YYYY-MM-DD; a full ISO timestamp is accepted and truncated to its date, and anything else is refused rather than treated as \"no filter\" (which used to widen the report to the account's entire history). An inverted window (`from` after `to`) is refused too. `template` is a published enum — executive, agency, creator, minimal, growth, board — and an unknown value is refused instead of becoming executive. `brandAccent` must be #rrggbb (#rgb is expanded); named colours, rgb() and 8-digit hex are refused instead of being replaced by the TokPortal default. White-labelling still depends on entitlement: `brandName` and `brandAccent` only apply on the full analytics tier with a Farmer plan, and are otherwise reset. The response carries `applied` — the template, brand name, brand accent and the exact date window the report covers — plus `canBrand`, so read those back instead of inspecting the rendered report. Do not send Idempotency-Key. The successful response contains a secret and is never stored in the replay ledger. A request with the header is rejected with IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE (400) before any ledger claim or operation execution.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAnalyticsReportRequest"}}}},"responses":{"200":{"description":"Created analytics report.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid report request. Idempotency-Key is not supported because the successful response contains a secret. Remove the header before retrying. Error code: IDEMPOTENCY_KEY_NOT_ALLOWED_FOR_SENSITIVE_RESPONSE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"Plan does not include this analytics level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"reject-sensitive-response","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/analytics/export/reports\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"title\": \"Launch campaign\",\n \"template\": \"executive\",\n \"brandName\": \"brandName\",\n \"brandAccent\": \"brandAccent\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/export/reports', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"title\": \"Launch campaign\",\n \"template\": \"executive\",\n \"brandName\": \"brandName\",\n \"brandAccent\": \"brandAccent\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/analytics/export/reports',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"title\\\": \\\"Launch campaign\\\",\\n \\\"template\\\": \\\"executive\\\",\\n \\\"brandName\\\": \\\"brandName\\\",\\n \\\"brandAccent\\\": \\\"brandAccent\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/analytics/export/reports\", strings.NewReader(\"{\\n \\\"title\\\": \\\"Launch campaign\\\",\\n \\\"template\\\": \\\"executive\\\",\\n \\\"brandName\\\": \\\"brandName\\\",\\n \\\"brandAccent\\\": \\\"brandAccent\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/export/reports/html":{"post":{"operationId":"exportAnalyticsReportHtml","summary":"Export analytics report HTML","description":"Creates a standalone downloadable HTML analytics report from the same body as createAnalyticsReport, and validates it identically: `from` and `to` are YYYY-MM-DD (a full ISO timestamp is truncated to its date, anything else is refused with INVALID_FIELD rather than treated as no filter), an inverted window is refused, `template` is the published enum (executive, agency, creator, minimal, growth, board) and an unknown value is refused instead of becoming executive, and `brandAccent` must be #rrggbb or #rgb. The body of the response is the HTML document itself, so what was applied travels in headers: X-TokPortal-Report-Template, X-TokPortal-Report-Can-Brand, X-TokPortal-Report-Brand-Name, X-TokPortal-Report-From, X-TokPortal-Report-To, alongside X-TokPortal-Export-Rows and X-TokPortal-Export-Accounts. Read those headers to confirm the window and the branding actually used.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAnalyticsReportRequest"}}}},"responses":{"200":{"description":"Standalone analytics report HTML.","content":{"text/html":{"schema":{"type":"string"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid report request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"Plan does not include this analytics level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/analytics/export/reports/html\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"title\": \"Launch campaign\",\n \"template\": \"executive\",\n \"brandName\": \"brandName\",\n \"brandAccent\": \"brandAccent\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/export/reports/html', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"title\": \"Launch campaign\",\n \"template\": \"executive\",\n \"brandName\": \"brandName\",\n \"brandAccent\": \"brandAccent\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/analytics/export/reports/html',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"title\\\": \\\"Launch campaign\\\",\\n \\\"template\\\": \\\"executive\\\",\\n \\\"brandName\\\": \\\"brandName\\\",\\n \\\"brandAccent\\\": \\\"brandAccent\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/analytics/export/reports/html\", strings.NewReader(\"{\\n \\\"title\\\": \\\"Launch campaign\\\",\\n \\\"template\\\": \\\"executive\\\",\\n \\\"brandName\\\": \\\"brandName\\\",\\n \\\"brandAccent\\\": \\\"brandAccent\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/series":{"get":{"operationId":"getAnalyticsSeries","summary":"Get analytics time series","description":"Daily or weekly time series for one metric, built from stored snapshots and date-scoped rollups — never a live fetch. `mode` selects cumulative totals, per-period gains, or raw snapshot values. Series are excluded on the Starter tier. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"metric","in":"query","required":false,"schema":{"type":"string","enum":["views","likes","comments","shares","followers"],"default":"views"}},{"name":"granularity","in":"query","required":false,"schema":{"type":"string","enum":["day","week"],"default":"day"}},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["cumulative","gained","snapshot"],"default":"cumulative"}},{"name":"account","in":"query","required":false,"description":"Repeatable account filter.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Analytics time series.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"Plan does not include this analytics level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/analytics/series?metric=example&granularity=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/series?metric=example&granularity=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/analytics/series?metric=example&granularity=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/analytics/series?metric=example&granularity=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/accounts/{id}":{"get":{"operationId":"getAnalyticsAccount","summary":"Get account analytics drilldown","description":"Analytics v2 drilldown for one account: current metrics, top posts and demographics. This is the current endpoint; getAccountAnalytics is the older compatibility shape of the same data. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Account analytics drilldown.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/accounts/{id}/refresh":{"post":{"operationId":"refreshAnalyticsAccount","summary":"Refresh analytics account","description":"Refreshes an owner-scoped account through Analytics v2. Comment collection is gated on three conditions: includeComments only runs when force is true, includePosts is not false, and the workspace holds the full analytics tier. The two you control are refusals, not silence — includeComments without force, or with includePosts false, fails with INVALID_FIELD for MCP callers and is reported for direct REST callers. The one you cannot control, the analytics tier, comes back on the response as applied.include_comments plus applied.include_comments_dropped_reason. The call can still return 200 with deduped: true and skippedReason: \"recent_snapshot\", which means nothing was refreshed. Check canRefreshAccountAnalytics first: a forced retry consumes the manual-refresh cooldown slot and the next one is rejected with 429. Refresh is blocked for revealed/detached, banned or inactive-Coverage accounts; permanently grandfathered accounts remain eligible.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshAnalyticsRequest"}}}},"responses":{"200":{"description":"Refresh result.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"Plan does not include this analytics level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Account refresh blocked. The response reason identifies the account or TokPortal Coverage state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Manual refresh cooldown active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"502":{"description":"Refresh provider failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"force\": false,\n \"includePosts\": false,\n \"includeComments\": false,\n \"forcePosts\": false\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"force\": false,\n \"includePosts\": false,\n \"includeComments\": false,\n \"forcePosts\": false\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"force\\\": false,\\n \\\"includePosts\\\": false,\\n \\\"includeComments\\\": false,\\n \\\"forcePosts\\\": false\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh\", strings.NewReader(\"{\\n \\\"force\\\": false,\\n \\\"includePosts\\\": false,\\n \\\"includeComments\\\": false,\\n \\\"forcePosts\\\": false\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/accounts/{id}/raw":{"get":{"operationId":"listAnalyticsAccountRawSnapshots","summary":"List raw account analytics snapshots","description":"Returns owner-scoped stored raw analytics payloads for a saved account. Full analytics tier only.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["bundle_social","apify","manual"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30,"default":5}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Raw account analytics snapshots.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"Plan does not include raw analytics payloads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/raw?source=example&limit=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/raw?source=example&limit=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/raw?source=example&limit=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/raw?source=example&limit=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/analytics":{"get":{"operationId":"getAccountAnalytics","summary":"Get account analytics compatibility view","description":"Legacy compatibility view of one account's analytics, kept for older integrations. New code should call getAnalyticsAccount instead. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Account analytics data.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/accounts/{id}/analytics/videos":{"get":{"operationId":"listAccountVideoAnalytics","summary":"List post analytics for an account","description":"Post-level analytics for one account, sortable by views, likes, engagement rate or upload date. Values are lifetime per-post totals. Call getAnalyticsContract before interpreting these numbers: top-line values are lifetime per-post totals, connected-account values are rolling windows, the two intentionally do not mirror each other, and your access tier may redact metrics — a missing field means unavailable, never zero.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","enum":["views","likes","engagement_rate","upload_date"],"default":"upload_date"}},{"name":"sort_order","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Post analytics list.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/videos?page=example&per_page=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/videos?page=example&per_page=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/videos?page=example&per_page=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics/videos?page=example&per_page=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/videos/{id}/analytics":{"get":{"operationId":"getVideoAnalytics","summary":"Get single video analytics","description":"Lifetime metrics for one tracked post. Interpret them with getAnalyticsContract: these are lifetime per-post totals and deliberately do not match the rolling-window figures shown for a connected account.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Video ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Video analytics.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Video not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/analytics\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/videos/{id}/ad-code-request":{"post":{"operationId":"createVideoAdCodeRequest","summary":"Request an ad code (TikTok Spark Code / Instagram Partner Code) for a finalized video","description":"Requests an ad code (TikTok Spark Code or Instagram Partner Code) for one finalized video and debits 7 credits, which are not refundable. The platform is resolved from the video itself and cannot be chosen. The video must be finalized on TikTok or Instagram with a live post link. Active TokPortal Coverage and a routable active account manager are required. TokPortal uses the account's current active manager, then its still-active manager relationship, then eligible non-cancelled order history. Completed bundles remain eligible without a delivery-age limit; cancelled orders are never restored. Assignment, debit, and task creation are atomic. Only one open request per video is allowed, so a request made on the wrong video cannot be replaced until it closes. Poll the GET endpoint to retrieve the code once the manager submits it.","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Video ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdCodeRequest"}}}},"responses":{"201":{"description":"Ad code request created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdCodeRequestResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid request or platform not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Video not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Coverage is inactive, no active account manager or non-cancelled support order is available, the video is not finalized, or an open request already exists. No credits are charged on these failures.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/ad-code-request\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"note\": \"note\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/ad-code-request', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"note\": \"note\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/ad-code-request',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"note\\\": \\\"note\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/ad-code-request\", strings.NewReader(\"{\\n \\\"note\\\": \\\"note\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]},"get":{"operationId":"getVideoAdCodeRequest","summary":"Get / poll the ad code for a video","description":"Returns the latest ad code request for the video. The `code` field is null until the manager submits it (status `in_review`) or it is delivered (status `finalized`).","tags":["Videos"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Video ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Latest ad code request (or null).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdCodeRequestResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Video not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/ad-code-request\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/ad-code-request', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/ad-code-request',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/videos/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/ad-code-request\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/comments":{"get":{"operationId":"getCommentPulse","summary":"Get comment pulse analytics","description":"Aggregated comment sentiment and themes across your posts, served from the analytics comment cache — never a live fetch. Full analytics tier only. Filters are not combinable: when `post` is supplied it takes precedence and `platform`, `country`, `account`, `workspace`, `from` and `to` are all ignored, and at most 12 post ids are sampled.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"platform","in":"query","required":false,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"schema":{"type":"string"}},{"name":"account","in":"query","required":false,"schema":{"type":"string"}},{"name":"post","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":24}},{"name":"postLimit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":6}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Comment pulse analytics.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"Plan does not include this analytics level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/analytics/comments?platform=example&country=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/comments?platform=example&country=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/analytics/comments?platform=example&country=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/analytics/comments?platform=example&country=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/accounts/{id}/comments":{"get":{"operationId":"listAnalyticsAccountComments","summary":"List comments for an account post","description":"Returns cached comment text for one tracked post of an account. Full analytics tier only; this read never calls the platform live.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Saved account ID.","schema":{"type":"string","format":"uuid"}},{"name":"trackedPostId","in":"query","required":false,"schema":{"type":"string"}},{"name":"postId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Post comments.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"Plan does not include this analytics level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Account or post not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/comments?trackedPostId=example&postId=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/comments?trackedPostId=example&postId=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/comments?trackedPostId=example&postId=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/analytics/accounts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/comments?trackedPostId=example&postId=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/analytics/posts/{id}/raw":{"get":{"operationId":"listAnalyticsPostRawSnapshots","summary":"List raw post analytics snapshots","description":"Returns owner-scoped stored raw analytics payloads for a tracked post. Full analytics tier only.","tags":["Analytics"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Tracked post ID.","schema":{"type":"string","format":"uuid"}},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["bundle_social","apify","manual"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30,"default":5}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Raw post analytics snapshots.","content":{"application/json":{"schema":{"type":"object"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"Plan does not include raw analytics payloads.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Post not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/analytics/posts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/raw?source=example&limit=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/analytics/posts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/raw?source=example&limit=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/analytics/posts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/raw?source=example&limit=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/analytics/posts/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/raw?source=example&limit=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/comments":{"get":{"operationId":"listCommentTasks","summary":"List comment tasks","description":"Lists owned comment tasks. execution_blocked and execution_block_reason identify tasks paused by inactive TokPortal Coverage; reads remain available while execution is paused.","tags":["Comments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","required":false,"description":"Items per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"status","in":"query","required":false,"description":"Filter by one status or a comma-separated list of statuses.","schema":{"type":"string"}},{"name":"saved_account_id","in":"query","required":false,"description":"Filter by a user-owned saved account ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paginated comment task list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentTaskListResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/comments?page=example&per_page=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/comments?page=example&per_page=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/comments?page=example&per_page=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/comments?page=example&per_page=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"post":{"operationId":"createCommentTasks","summary":"Create comment tasks","description":"Creates one comment task or a partial-success batch of up to 200. Each accepted task costs 1 credit. The target is any public TikTok or Instagram video, including a third party's — that is the intended use — while the posting account must be one of your own delivered accounts and its platform must match the target's (COMMENT_PLATFORM_MISMATCH otherwise). Deduplicate locally on (saved_account_id, target URL, comment_text): two different Idempotency-Keys carrying the same comment bill twice. The saved account must be client-owned, manager-assigned, and allowed to execute tasks by TokPortal Coverage, unless it is permanently grandfathered. TokPortal locks and revalidates the account and Coverage before the accepted-task debit and all accepted inserts commit in one transaction. Rejected rows are never charged. Read credits_charged instead of calculating it from the request, and read meta.rejected_count and each row's reason rather than inferring success from the 201. Send an Idempotency-Key and reuse the same key, method, path, and body after an uncertain transport result so the completed response is replayed without a second charge.","tags":["Comments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended for this credit or workflow mutation. Use one unique key per logical request and reuse the same key only with the same method, path, query, and body after an uncertain result. Maximum 255 characters.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommentTaskRequest"}}}},"responses":{"201":{"description":"Created and rejected comment-task rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommentTasksResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid comment task request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Single task blocked by account state or inactive TokPortal Coverage. For a batch, inspect each rejected row instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"500":{"description":"The batch outcome could not be confirmed. Retry the exact request with the same Idempotency-Key; do not create a new logical request until reconciled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/comments\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Idempotency-Key: createCommentTasks-example-1\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"saved_account_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\",\n \"comment_text\": \"comment_text\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/comments', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n 'Idempotency-Key': 'createCommentTasks-example-1',\n },\n body: JSON.stringify({\n \"saved_account_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\",\n \"comment_text\": \"comment_text\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/comments',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"], \"Idempotency-Key\": \"createCommentTasks-example-1\"},\n json=json.loads(\"{\\n \\\"saved_account_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\",\\n \\\"comment_text\\\": \\\"comment_text\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/comments\", strings.NewReader(\"{\\n \\\"saved_account_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\",\\n \\\"comment_text\\\": \\\"comment_text\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Idempotency-Key\", \"createCommentTasks-example-1\")\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/comments/{id}":{"get":{"operationId":"getCommentTask","summary":"Get a comment task","description":"Returns one owned comment task, including whether inactive TokPortal Coverage currently blocks manager execution and the stable block reason.","tags":["Comments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Comment task ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Comment task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentTaskResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Comment task not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"delete":{"operationId":"deleteCommentTask","summary":"Cancel a pending comment task","description":"Cancels an owned task only while its status is pending. The terminal transition and refund of the task's exact stored credit cost commit atomically and are idempotent. Current tasks refund 1 credit; credits_refunded remains authoritative for historical tasks. Cancellation remains available when Coverage is paused because it stops pending work rather than executing it. Reuse the same Idempotency-Key after an uncertain transport result.","tags":["Comments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Comment task ID.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended for this credit or workflow mutation. Use one unique key per logical request and reuse the same key only with the same method, path, query, and body after an uncertain result. Maximum 255 characters.","schema":{"type":"string","minLength":1,"maxLength":255}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Cancellation and exact refund result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelCommentTaskResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Comment task not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Only a pending task can be cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Idempotency-Key: deleteCommentTask-example-1\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'DELETE',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Idempotency-Key': 'deleteCommentTask-example-1',\n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'DELETE',\n 'https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"], \"Idempotency-Key\": \"deleteCommentTask-example-1\"}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"DELETE\", \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Idempotency-Key\", \"deleteCommentTask-example-1\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/comments/{id}/approve":{"post":{"operationId":"approveCommentTask","summary":"Approve a manually confirmed comment task","description":"Approves and finalizes an owned manually_confirmed task. Execution is blocked while TokPortal Coverage is inactive; inspect MANAGED_ACCOUNT_TASK_BLOCKED and reactivate a recoverable account first.","tags":["Comments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Comment task ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"responses":{"200":{"description":"Approved comment task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentTaskResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Comment task not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Comment task status cannot be approved, or TokPortal Coverage currently blocks execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/approve\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/approve', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/approve',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/approve\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/comments/{id}/dispute":{"post":{"operationId":"disputeCommentTask","summary":"Dispute a manually confirmed comment task","description":"Returns an owned manually_confirmed task to pending corrections. Execution is blocked while TokPortal Coverage is inactive; inspect MANAGED_ACCOUNT_TASK_BLOCKED and reactivate a recoverable account first.","tags":["Comments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Comment task ID.","schema":{"type":"string","format":"uuid"}},{"name":"X-TokPortal-Dry-Run","in":"header","required":false,"description":"Send `true` (or `1`/`yes`) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds `dry_run: true`, `dry_run_notice`, and — on credit-spending operations — `credits_would_charge` carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).","schema":{"type":"string","enum":["true","1","yes"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeCommentRequest"}}}},"responses":{"200":{"description":"Disputed comment task.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentTaskResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid dispute reason.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"Comment task not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Comment task status cannot be disputed, or TokPortal Coverage currently blocks execution.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"X-TokPortal-Dry-Run":{"description":"Present and set to `true` when the request was simulated. This is the only dry-run marker on error responses, so a client can confirm it spent nothing without parsing the body.","schema":{"type":"string","enum":["true"]}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/dispute\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"reason\": \"Please review this item.\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/dispute', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"reason\": \"Please review this item.\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/dispute',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"reason\\\": \\\"Please review this item.\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/dispute\", strings.NewReader(\"{\\n \\\"reason\\\": \\\"Please review this item.\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/comments/{id}/verifications":{"get":{"operationId":"listCommentTaskVerifications","summary":"List comment task verification events","description":"Lists verifier attempts for one owned task. This read remains available while TokPortal Coverage pauses task execution.","tags":["Comments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Comment task ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Verification timeline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentVerificationTimelineResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"Missing, invalid, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"Comment task not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verifications\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verifications', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verifications',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/comments/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/verifications\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/status":{"get":{"operationId":"getAiStatus","summary":"Read AI availability without starting provider work","tags":["AI"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiStatus"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/status\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/status', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/status',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/status\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/models":{"get":{"operationId":"aiCatalog","summary":"Discover AI models and capabilities","description":"Lists public model aliases and availability. A blocked capability is not usable. Fetch the chosen model schema before quoting; never infer support from a model name.","tags":["AI"],"parameters":[{"name":"capability","in":"query","required":false,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AiModel"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":true,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/models?capability=example&cursor=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/models?capability=example&cursor=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/models?capability=example&cursor=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/models?capability=example&cursor=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/models/{model_id}":{"get":{"operationId":"aiModelSchema","summary":"Read a model's current input schema and capabilities","tags":["AI"],"parameters":[{"name":"model_id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"operation","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiModel"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":true,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/models/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c?operation=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/models/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c?operation=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/models/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c?operation=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/models/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c?operation=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/quotes":{"post":{"operationId":"aiQuote","summary":"Quote an AI operation in USD before spending","description":"Free preflight; never starts paid provider work. Freezes model, operation and inputs into a workspace-bound quote valid for 15 minutes. Read availability and the maximum USD price, get user approval, then generate with this quote ID. The AI dollar wallet is separate from TokPortal management credits.","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiQuoteRequest"}}}},"responses":{"201":{"description":"Immutable quote created; no paid provider work started.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiQuote"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-mcp-expose":true,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/quotes\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"model\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/quotes', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"model\": \"model\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/quotes',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"model\\\": \\\"model\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/quotes\", strings.NewReader(\"{\\n \\\"model\\\": \\\"model\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/generations":{"post":{"operationId":"aiGenerate","summary":"Generate media with automatic AI wallet billing","description":"Send model, prompt and model-specific controls directly. The server prices and reserves funds automatically within the key's approved per-job and monthly limits. Optional max_cost_usd sets a lower request cap. A separate quote is not required; quote_id plus max_cost_usd remains supported for explicit cost previews. Requires AI spending permission, wallet balance and Idempotency-Key. Reuse the same key and body after uncertainty. Does not publish. Poll with ai_inspect resource jobs. For video drafts, propose 480p (lower cost), 720p for a balance, or 1080p for final quality; respect the user's choice.","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiGenerationRequest"}}}},"responses":{"202":{"description":"Accepted as a durable TokPortal job. Poll its local ID; do not resubmit.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiJob"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":true,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/generations\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"model\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/generations', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"model\": \"model\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/generations',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"model\\\": \\\"model\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/generations\", strings.NewReader(\"{\\n \\\"model\\\": \\\"model\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/jobs":{"get":{"operationId":"listAiJobs","summary":"List AI jobs","tags":["AI"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AiJob"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/jobs?cursor=example&limit=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/jobs?cursor=example&limit=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/jobs?cursor=example&limit=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/jobs?cursor=example&limit=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/jobs/{job_id}":{"get":{"operationId":"getAiJob","summary":"Read an AI job","tags":["AI"],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiJob"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/jobs/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/jobs/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/jobs/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/jobs/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/jobs/{job_id}/cancel":{"post":{"operationId":"cancelAiJob","summary":"Request cancellation of an AI job","description":"Cancellation is best effort. Accepted provider work may remain billable; cancellation is not a refund promise.","tags":["AI"],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiJob"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/jobs/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/cancel\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/jobs/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/cancel', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/jobs/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/cancel',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/jobs/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/cancel\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/assets":{"get":{"operationId":"listAiAssets","summary":"List reusable AI media assets","tags":["AI"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AiAsset"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/assets?cursor=example&limit=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/assets?cursor=example&limit=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/assets?cursor=example&limit=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/assets?cursor=example&limit=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/assets/import":{"post":{"operationId":"importAiAsset","summary":"Import a media URL into the AI asset library","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiAssetImportRequest"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiAsset"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/assets/import\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://example.com/resource\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/assets/import', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"url\": \"https://example.com/resource\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/assets/import',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"url\\\": \\\"https://example.com/resource\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/assets/import\", strings.NewReader(\"{\\n \\\"url\\\": \\\"https://example.com/resource\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/assets/uploads":{"post":{"operationId":"createAiUpload","summary":"Create a signed media upload","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiUploadRequest"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/assets/uploads\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"media.mp4\",\n \"content_type\": \"video/mp4\",\n \"size_bytes\": 25\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/assets/uploads', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"filename\": \"media.mp4\",\n \"content_type\": \"video/mp4\",\n \"size_bytes\": 25\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/assets/uploads',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"filename\\\": \\\"media.mp4\\\",\\n \\\"content_type\\\": \\\"video/mp4\\\",\\n \\\"size_bytes\\\": 25\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/assets/uploads\", strings.NewReader(\"{\\n \\\"filename\\\": \\\"media.mp4\\\",\\n \\\"content_type\\\": \\\"video/mp4\\\",\\n \\\"size_bytes\\\": 25\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/assets/uploads/complete":{"post":{"operationId":"completeAiUpload","summary":"Verify and register a completed media upload","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiUploadCompleteRequest"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiAsset"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/assets/uploads/complete\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"upload_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/assets/uploads/complete', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"upload_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/assets/uploads/complete',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"upload_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/assets/uploads/complete\", strings.NewReader(\"{\\n \\\"upload_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/assets/{asset_id}":{"get":{"operationId":"getAiAsset","summary":"Read an AI media asset","tags":["AI"],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiAsset"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"patch":{"operationId":"updateAiAsset","summary":"Update AI asset metadata","tags":["AI"],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiAssetUpdateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiAsset"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"name\",\n \"metadata\": {}\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"name\": \"name\",\n \"metadata\": {}\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"name\\\": \\\"name\\\",\\n \\\"metadata\\\": {}\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", strings.NewReader(\"{\\n \\\"name\\\": \\\"name\\\",\\n \\\"metadata\\\": {}\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]},"delete":{"operationId":"deleteAiAsset","summary":"Delete an AI asset","tags":["AI"],"parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'DELETE',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'DELETE',\n 'https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"DELETE\", \"https://app.tokportal.com/api/ext/ai/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/collections":{"get":{"operationId":"listAiCollections","summary":"List AI asset collections","tags":["AI"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AiCollection"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/collections?cursor=example&limit=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections?cursor=example&limit=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/collections?cursor=example&limit=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/collections?cursor=example&limit=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"post":{"operationId":"createAiCollection","summary":"Create an AI asset collection","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCollectionRequest"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiCollection"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/collections\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"name\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"name\": \"name\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/collections',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"name\\\": \\\"name\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/collections\", strings.NewReader(\"{\\n \\\"name\\\": \\\"name\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/collections/{collection_id}":{"get":{"operationId":"getAiCollection","summary":"Read an AI asset collection","tags":["AI"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiCollection"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"patch":{"operationId":"updateAiCollection","summary":"Update an AI asset collection","tags":["AI"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCollectionRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiCollection"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"name\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"name\": \"name\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"name\\\": \\\"name\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", strings.NewReader(\"{\\n \\\"name\\\": \\\"name\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]},"delete":{"operationId":"deleteAiCollection","summary":"Delete an AI asset collection","tags":["AI"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'DELETE',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'DELETE',\n 'https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"DELETE\", \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/collections/{collection_id}/assets":{"get":{"operationId":"listAiCollectionAssets","summary":"List every asset reference in an owned collection","tags":["AI"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AiReference"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets?cursor=example&limit=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets?cursor=example&limit=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets?cursor=example&limit=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets?cursor=example&limit=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"post":{"operationId":"addAiCollectionAsset","summary":"Add an asset to a collection","tags":["AI"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},"required":["asset_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"asset_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"asset_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"asset_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets\", strings.NewReader(\"{\\n \\\"asset_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/collections/{collection_id}/assets/{asset_id}":{"delete":{"operationId":"removeAiCollectionAsset","summary":"Remove an asset from a collection","tags":["AI"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'DELETE',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'DELETE',\n 'https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"DELETE\", \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"patch":{"operationId":"updateAiCollectionAsset","summary":"Rename a collection asset reference","tags":["AI"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiReference"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"name\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"name\": \"name\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"name\\\": \\\"name\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", strings.NewReader(\"{\\n \\\"name\\\": \\\"name\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/collections/{collection_id}/assets/{asset_id}/refresh":{"post":{"operationId":"refreshAiCollectionAsset","summary":"Refresh a collection asset reference processing status","tags":["AI"],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiReference"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/collections/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/assets/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/library":{"get":{"operationId":"listAiLibrary","summary":"Browse the available reusable reference library","tags":["AI"],"parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":300}},{"name":"page_number","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000000,"default":1}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":30}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiLibrary"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/library?query=example&page_number=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/library?query=example&page_number=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/library?query=example&page_number=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/library?query=example&page_number=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/library/{reference_id}/thumbnail":{"get":{"operationId":"getAiLibraryThumbnail","summary":"Read an authorized reference thumbnail","tags":["AI"],"parameters":[{"name":"reference_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}}],"responses":{"200":{"description":"Private thumbnail bytes; authenticate with the same TokPortal key.","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/library/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/thumbnail\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/library/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/thumbnail', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/library/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/thumbnail',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/library/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/thumbnail\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/verifications":{"get":{"operationId":"listAiVerifications","summary":"List human-verification sessions","tags":["AI"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AiVerification"}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/verifications?cursor=example&limit=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/verifications?cursor=example&limit=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/verifications?cursor=example&limit=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/verifications?cursor=example&limit=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"post":{"operationId":"createAiVerification","summary":"Create an explicitly authorized human-verification session","description":"Starts an external human-verification flow, not a generated model job. Availability requires explicit operational approval of provider pricing. No claim that this is free. The returned link expires quickly and permits a single verification attempt.","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiVerificationRequest"}}}},"responses":{"201":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiVerification"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/verifications\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"name\",\n \"consent\": true\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/verifications', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"name\": \"name\",\n \"consent\": true\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/verifications',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"name\\\": \\\"name\\\",\\n \\\"consent\\\": true\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/verifications\", strings.NewReader(\"{\\n \\\"name\\\": \\\"name\\\",\\n \\\"consent\\\": true\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/verifications/{verification_id}":{"get":{"operationId":"getAiVerification","summary":"Read a locally persisted human-verification session","tags":["AI"],"parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiVerification"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/verifications/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/verifications/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/verifications/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/verifications/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/verifications/{verification_id}/refresh":{"post":{"operationId":"refreshAiVerification","summary":"Explicitly refresh a human-verification result","description":"Queries the provider using the server-held verification token. Never auto-retry a one-attempt verification. Use the same idempotency key after an uncertain result.","tags":["AI"],"parameters":[{"name":"verification_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiVerification"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/verifications/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/verifications/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/verifications/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/verifications/9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c/refresh\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/chat/completions":{"post":{"operationId":"createAiChatCompletion","summary":"Run a quoted text operation with optional streaming","description":"Uses the quote's frozen prompt/options, not a second mutable prompt. stream=false returns JSON; stream=true returns TokPortal Server-Sent Events for job lifecycle and final results, not an upstream token-by-token compatibility stream. A client disconnect is not proof the provider cancelled. Reconcile the job/request before retrying. MCP uses ai_generate for a pollable job instead.","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiTextRequest"}}}},"responses":{"200":{"description":"TokPortal job lifecycle and result events (stream=true)","content":{"text/event-stream":{"schema":{"type":"string"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"202":{"description":"Durable text job accepted (stream=false).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiJob"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/chat/completions\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"quote_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\",\n \"max_cost_usd\": \"2.500000\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/chat/completions', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"quote_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\",\n \"max_cost_usd\": \"2.500000\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/chat/completions',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"quote_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\",\\n \\\"max_cost_usd\\\": \\\"2.500000\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/chat/completions\", strings.NewReader(\"{\\n \\\"quote_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\",\\n \\\"max_cost_usd\\\": \\\"2.500000\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/responses":{"post":{"operationId":"createAiResponse","summary":"Run a quoted text operation with optional streaming","description":"Uses the quote's frozen prompt/options, not a second mutable prompt. stream=false returns JSON; stream=true returns TokPortal Server-Sent Events for job lifecycle and final results, not an upstream token-by-token compatibility stream. A client disconnect is not proof the provider cancelled. Reconcile the job/request before retrying. MCP uses ai_generate for a pollable job instead.","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiTextRequest"}}}},"responses":{"200":{"description":"TokPortal job lifecycle and result events (stream=true)","content":{"text/event-stream":{"schema":{"type":"string"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"202":{"description":"Durable text job accepted (stream=false).","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiJob"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/responses\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"quote_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\",\n \"max_cost_usd\": \"2.500000\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/responses', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"quote_id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\",\n \"max_cost_usd\": \"2.500000\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/responses',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"quote_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\",\\n \\\"max_cost_usd\\\": \\\"2.500000\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/responses\", strings.NewReader(\"{\\n \\\"quote_id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\",\\n \\\"max_cost_usd\\\": \\\"2.500000\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/wallet":{"get":{"operationId":"getAiWallet","summary":"Read the separate AI USD wallet","tags":["AI"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiWallet"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/wallet\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/wallet', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/wallet',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/wallet\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/wallet/transactions":{"get":{"operationId":"listAiWalletTransactions","summary":"Read AI USD wallet transactions","tags":["AI"],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["items"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/wallet/transactions?cursor=example&limit=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/wallet/transactions?cursor=example&limit=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/wallet/transactions?cursor=example&limit=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/wallet/transactions?cursor=example&limit=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/wallet/topups":{"post":{"operationId":"aiTopup","summary":"Create an explicitly approved AI wallet top-up checkout","description":"Billing action, never an implied prerequisite to generation. Only call after the user explicitly approves the displayed USD amount. Return the payment URL for the user to complete; never claim the wallet was credited merely because checkout was created.","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiTopupRequest"}}}},"responses":{"201":{"description":"Checkout created; this does not confirm a payment or wallet credit.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":true,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/wallet/topups\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"amount_usd\": \"2.500000\",\n \"billing_consent\": true\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/wallet/topups', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"amount_usd\": \"2.500000\",\n \"billing_consent\": true\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/wallet/topups',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"amount_usd\\\": \\\"2.500000\\\",\\n \\\"billing_consent\\\": true\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/wallet/topups\", strings.NewReader(\"{\\n \\\"amount_usd\\\": \\\"2.500000\\\",\\n \\\"billing_consent\\\": true\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/wallet/auto-topup":{"get":{"operationId":"getAiAutoTopup","summary":"Read AI automatic top-up settings","tags":["AI"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/wallet/auto-topup\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/wallet/auto-topup', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/wallet/auto-topup',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/wallet/auto-topup\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"patch":{"operationId":"updateAiAutoTopup","summary":"Configure recurring AI wallet top-up authority","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiAutoTopupRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/ai/wallet/auto-topup\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"enabled\": false\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/wallet/auto-topup', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"enabled\": false\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/ai/wallet/auto-topup',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"enabled\\\": false\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/ai/wallet/auto-topup\", strings.NewReader(\"{\\n \\\"enabled\\\": false\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/access":{"get":{"operationId":"getAiAccess","summary":"Read this key's AI permissions and budgets","tags":["AI"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/access\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/access', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/access',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/access\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]},"patch":{"operationId":"updateAiAccess","summary":"Configure explicitly approved AI key access and budgets","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiAccessRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":false,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/ai/access\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"enabled\": false\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/access', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"enabled\": false\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/ai/access',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"enabled\\\": false\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/ai/access\", strings.NewReader(\"{\\n \\\"enabled\\\": false\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/inspect":{"get":{"operationId":"aiInspect","summary":"Inspect AI jobs, media, wallet or permissions","description":"Read-only facade over fixed AI resources. Optional id reads one owned job, asset, collection, or verification; omit it to list. wallet, transactions, access, auto_topup and status do not accept a resource ID. No provider work or payment is started.","tags":["AI"],"parameters":[{"name":"resource","in":"query","required":true,"schema":{"type":"string","enum":["status","jobs","assets","collections","collection_assets","library","verifications","wallet","transactions","access","auto_topup"]}},{"name":"id","in":"query","required":false,"schema":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":300}},{"name":"page_number","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":1000000}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"$ref":"#/components/schemas/AiInspectResult"}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}}}}},"x-mcp-expose":true,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X GET \"https://app.tokportal.com/api/ext/ai/inspect?resource=example&id=example\" \\\n -H \"X-API-Key: sk_your_key_here\""},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/inspect?resource=example&id=example', {\n method: 'GET',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n \n }\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'GET',\n 'https://app.tokportal.com/api/ext/ai/inspect?resource=example&id=example',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]}\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"GET\", \"https://app.tokportal.com/api/ext/ai/inspect?resource=example&id=example\", nil)\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/manage":{"post":{"operationId":"aiManage","summary":"Manage AI media, collections, cancellations and human verification","description":"A fixed action enum, never an arbitrary HTTP proxy. Review the action before approving: deletion can remove media, cancellation does not guarantee a refund, and verification starts or refreshes an explicitly approved external human-verification session. All actions require Idempotency-Key. Verification is operationally gated until its provider pricing and consent requirements are approved.","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiManageRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":true,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://app.tokportal.com/api/ext/ai/manage\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"action\": \"cancel_job\",\n \"id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/manage', {\n method: 'POST',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"action\": \"cancel_job\",\n \"id\": \"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\"\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'POST',\n 'https://app.tokportal.com/api/ext/ai/manage',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"action\\\": \\\"cancel_job\\\",\\n \\\"id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"POST\", \"https://app.tokportal.com/api/ext/ai/manage\", strings.NewReader(\"{\\n \\\"action\\\": \\\"cancel_job\\\",\\n \\\"id\\\": \\\"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c\\\"\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}},"/ai/configure":{"patch":{"operationId":"aiConfigure","summary":"Configure AI permissions, budgets or automatic billing","description":"Changes future spending authority. resource selects access or auto_topup. Require explicit user approval for enabling generation/billing or raising limits. Enabling automatic top-ups requires billing_consent:true. Never silently grant a key permissions or turn on recurring payments to make another operation succeed.","tags":["AI"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for a logical spending/payment request. Reuse the same key and identical body after an uncertain result; never retry with a new key.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiConfigureRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"data":{"type":"object","additionalProperties":true}},"required":["success","data"],"additionalProperties":false}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"400":{"description":"Invalid input, missing idempotency key, or unsupported operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"401":{"description":"A valid TokPortal API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"402":{"description":"Insufficient available funds in the separate AI USD wallet. No automatic checkout or debit is initiated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"403":{"description":"The key does not have permission, or explicit AI/billing consent is missing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"404":{"description":"The resource does not exist in this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"409":{"description":"Conflict, expired quote, changed request, or job not cancellable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"422":{"description":"A model capability or input combination is unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"429":{"description":"Rate, concurrency, or spending limit reached. Retry only as instructed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}},"503":{"description":"AI is disabled or a required capability, schema, or provider is unavailable. No fallback spend occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"X-TokPortal-API-Version":{"description":"Current TokPortal public API contract version.","schema":{"type":"string","example":"2026-05-25"}},"X-TokPortal-API-Stability":{"description":"Stability channel for the public API contract.","schema":{"type":"string","example":"stable"}},"X-TokPortal-Request-ID":{"description":"Request correlation ID. Echoes a valid X-Request-ID request header or uses a generated req_ identifier.","schema":{"type":"string","example":"req_0123456789abcdef0123456789abcdef"}},"X-RateLimit-Limit":{"description":"Maximum token bucket capacity for the authenticated API key.","schema":{"type":"integer","example":120}},"X-RateLimit-Remaining":{"description":"Approximate requests remaining for the authenticated API key after this request.","schema":{"type":"integer","example":119}},"X-RateLimit-Reset":{"description":"Unix timestamp at which the current one-minute budget window rolls over.","schema":{"type":"integer","example":1779724800}},"Retry-After":{"description":"Seconds to wait before retrying after a `rate_limited` response. Present on 429 responses only.","schema":{"type":"integer","example":12}},"Idempotent-Replayed":{"description":"Present with value true when a mutating request is replayed from a completed Idempotency-Key.","schema":{"type":"string","enum":["true"]}}}}},"x-idempotency-policy":"standard","x-mcp-expose":true,"x-tokportal-feature":"ai","x-tokportal-dry-run":false,"x-mcp-annotations":{"readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://app.tokportal.com/api/ext/ai/configure\" \\\n -H \"X-API-Key: sk_your_key_here\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"resource\": \"access\",\n \"config\": {\n \"enabled\": false\n }\n}'"},{"lang":"JavaScript","label":"Node","source":"const response = await fetch('https://app.tokportal.com/api/ext/ai/configure', {\n method: 'PATCH',\n headers: {\n 'X-API-Key': process.env.TOKPORTAL_API_KEY!,\n 'Content-Type': 'application/json',\n \n },\n body: JSON.stringify({\n \"resource\": \"access\",\n \"config\": {\n \"enabled\": false\n }\n})\n});\nconst data = await response.json();"},{"lang":"Python","label":"Python","source":"import json\nimport os\nimport requests\n\nresponse = requests.request(\n 'PATCH',\n 'https://app.tokportal.com/api/ext/ai/configure',\n headers={\"X-API-Key\": os.environ[\"TOKPORTAL_API_KEY\"]},\n json=json.loads(\"{\\n \\\"resource\\\": \\\"access\\\",\\n \\\"config\\\": {\\n \\\"enabled\\\": false\\n }\\n}\")\n)\nprint(response.json())"},{"lang":"Go","label":"Go","source":"req, _ := http.NewRequest(\"PATCH\", \"https://app.tokportal.com/api/ext/ai/configure\", strings.NewReader(\"{\\n \\\"resource\\\": \\\"access\\\",\\n \\\"config\\\": {\\n \\\"enabled\\\": false\\n }\\n}\"))\nreq.Header.Set(\"X-API-Key\", os.Getenv(\"TOKPORTAL_API_KEY\"))\nreq.Header.Set(\"Content-Type\", \"application/json\")\nresp, err := http.DefaultClient.Do(req)"}]}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"TokPortal API key. New keys use the format sk_ followed by 64 lowercase hex characters, are stored as SHA-256 hashes, are shown once at creation, and should never be sent in query parameters."}},"schemas":{"CountryOption":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string","example":"DE"},"name":{"type":"string","example":"Germany"}}},"CountriesResponse":{"type":"object","required":["data","videos_only_countries"],"properties":{"data":{"type":"array","description":"Countries where TokPortal can provision a new account.","items":{"$ref":"#/components/schemas/CountryOption"}},"videos_only_countries":{"type":"array","description":"Countries where videos can be ordered for an existing TokPortal account. This can include countries absent from data.","items":{"$ref":"#/components/schemas/CountryOption"}}}},"Pagination":{"type":"object","required":["page","per_page","total","total_pages"],"properties":{"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0},"total_pages":{"type":"integer","minimum":0}},"additionalProperties":false},"PublicAccountBan":{"type":["object","null"],"required":["reason","banned_at"],"properties":{"reason":{"type":["string","null"]},"banned_at":{"type":["string","null"],"format":"date-time"},"appeal_status":{"type":["string","null"],"enum":["appeal_refused","no_appeal_banned",null]},"screenshot_url":{"type":["string","null"],"format":"uri"}},"additionalProperties":false},"PublicAccountBanResolution":{"type":["object","null"],"description":"Staff commercial resolution of a confirmed ban. Null while the case is still awaiting the staff decision.","required":["resolution","reason_code","refund_credits","resolved_at"],"properties":{"resolution":{"type":"string","enum":["refund","remake","no_remake"]},"reason_code":{"type":["string","null"],"description":"Machine-readable resolution reason, e.g. eligible_refund, eligible_credit_restoration, replacement_approved, tos_ban, tos_violation, content_related, custom. tos_ban means the account was banned for a direct Terms of Service violation and is not refundable."},"refund_credits":{"type":"integer","minimum":0},"resolved_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"PublicAccountBanAppeal":{"type":["object","null"],"description":"Latest validated ban report for this account, across the whole lifecycle — including appeal_pending (platform appeal filed, account unavailable but not yet banned) and the staff commercial resolution. Null when the account has no ban report.","required":["id","status","reported_at","decided_at","resolution"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["appeal_pending","appeal_accepted","appeal_refused","no_appeal_banned"]},"reported_at":{"type":["string","null"],"format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"},"resolution":{"$ref":"#/components/schemas/PublicAccountBanResolution"}},"additionalProperties":false},"PublicAccountBanReport":{"type":"object","description":"A validated ban report (staff/CM validated — never a raw park-scan detection) with its appeal lifecycle and staff resolution.","required":["id","account_id","username","platform","bundle_id","order_id","status","reported_at","decided_at","updated_at","resolution"],"properties":{"id":{"type":"string","format":"uuid"},"account_id":{"type":["string","null"],"format":"uuid","description":"Saved account ID. Null after a staff reset deleted the account row; use bundle_id as the stable anchor."},"username":{"type":["string","null"]},"platform":{"type":"string"},"bundle_id":{"type":["string","null"],"format":"uuid"},"order_id":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["appeal_pending","appeal_accepted","appeal_refused","no_appeal_banned"]},"reported_at":{"type":["string","null"],"format":"date-time","description":"First durable manager report of the ban incident."},"decided_at":{"type":["string","null"],"format":"date-time","description":"Platform appeal decision timestamp. Null while the appeal is pending."},"updated_at":{"type":["string","null"],"format":"date-time"},"resolution":{"$ref":"#/components/schemas/PublicAccountBanResolution"},"screenshot_url":{"type":["string","null"],"format":"uri","description":"Signed 7-day URL of the ban-evidence screenshot. Only present with include_screenshots=true."}},"additionalProperties":false},"AccountBanListResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicAccountBanReport"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false},"PublicAccountRemade":{"type":"object","required":["was_remade","remade_count","old_username","remade_at"],"properties":{"was_remade":{"type":"boolean"},"remade_count":{"type":"integer","minimum":0},"old_username":{"type":["string","null"]},"remade_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"PublicAccountOwningFee":{"type":"object","required":["enabled","status","reveal_endpoint","verification_code_endpoint","notice"],"properties":{"enabled":{"type":"boolean","enum":[true]},"status":{"type":["string","null"]},"reveal_endpoint":{"type":"string"},"verification_code_endpoint":{"type":"string"},"notice":{"type":"string"}},"additionalProperties":false},"ManagedAccountSubscription":{"type":"object","required":["id","saved_account_id","status","recorded_status","period_expired","delivered_at","current_period_start","current_period_end","period_rate_credits","lapsed_since","ended_at","ended_reason","cancelled_at","cancellation_reason","lock_version","unpaid_periods","reactivation_credits","quote_generated_at","reactivation_quote","task_access"],"properties":{"id":{"type":"string","format":"uuid"},"saved_account_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"Effective Coverage lifecycle state at quote_generated_at. At the exact current_period_end boundary this is lapsed even if recorded_status is still included or active until the renewal worker persists the transition. cancelled is the recoverable client-initiated pause; ended_cancelled is a legacy terminal state and is never caused by bundle completion or cancellation.","enum":["included","active","lapsed","cancelled","unrecoverable","ended_ban","ended_revealed","ended_cancelled"]},"recorded_status":{"type":"string","description":"Durable database lifecycle marker at read time. Use status and task_access for decisions; this field exists to make the short asynchronous renewal boundary explicit.","enum":["included","active","lapsed","cancelled","unrecoverable","ended_ban","ended_revealed","ended_cancelled"]},"period_expired":{"type":"boolean","description":"True when a recorded included or active row has reached current_period_end. Task access is already blocked and the reactivation quote is actionable without waiting for cron."},"delivered_at":{"type":"string","format":"date-time"},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"period_rate_credits":{"type":"integer","minimum":0},"lapsed_since":{"type":["string","null"],"format":"date-time"},"ended_at":{"type":["string","null"],"format":"date-time"},"ended_reason":{"type":["string","null"]},"cancelled_at":{"type":["string","null"],"format":"date-time"},"cancellation_reason":{"type":["string","null"]},"lock_version":{"type":"integer","minimum":0,"description":"Monotonic subscription snapshot version. Send it back as expected_lock_version when reactivating."},"unpaid_periods":{"type":"integer","minimum":0},"reactivation_credits":{"type":["integer","null"],"minimum":0,"description":"Exact current reactivation charge. Zero is valid when the current billing period is already paid or included; benefits remain paused until reactivation. Null means the state is not reactivatable."},"quote_generated_at":{"type":"string","format":"date-time"},"reactivation_quote":{"anyOf":[{"$ref":"#/components/schemas/ManagedAccountReactivationQuote"},{"type":"null"}]},"task_access":{"type":"string","enum":["allowed","blocked"],"description":"Effective task admission at quote_generated_at. This becomes blocked exactly at current_period_end, independently of renewal-worker timing."}},"additionalProperties":false},"ManagedAccountReactivationQuote":{"type":"object","required":["credits","unpaid_periods","current_period_end","lock_version","quoted_at"],"properties":{"credits":{"type":"integer","minimum":0},"unpaid_periods":{"type":"integer","minimum":0},"current_period_end":{"type":"string","format":"date-time"},"lock_version":{"type":"integer","minimum":0},"quoted_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"ManagedAccountSubscriptionReactivationRequest":{"type":"object","required":["expected_credits","expected_current_period_end","expected_lock_version"],"properties":{"expected_credits":{"type":"integer","minimum":0,"maximum":2147483647,"description":"The exact reactivation_credits value from the latest Coverage snapshot. Zero is valid."},"expected_current_period_end":{"type":"string","format":"date-time","description":"The current_period_end value from the same snapshot."},"expected_lock_version":{"type":"integer","minimum":0,"maximum":2147483647,"description":"The lock_version value from the same snapshot."}},"additionalProperties":false},"PublicAccountSummary":{"type":"object","description":"Safe delivered-account metadata. Credential, mailbox, verification-code, token, and internal manager fields are not part of this object.","required":["id","platform","username","visible_name","biography","profile_picture_url","country","link_in_bio","profile_url","banned","ban","ban_appeal","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["tiktok","instagram","youtube"]},"username":{"type":["string","null"]},"visible_name":{"type":["string","null"]},"biography":{"type":["string","null"]},"profile_picture_url":{"type":["string","null"]},"country":{"type":["string","null"]},"link_in_bio":{"type":["string","null"]},"profile_url":{"type":["string","null"]},"banned":{"type":"boolean"},"ban":{"$ref":"#/components/schemas/PublicAccountBan"},"ban_appeal":{"$ref":"#/components/schemas/PublicAccountBanAppeal"},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"PublicAccountDetail":{"type":"object","description":"Safe delivered-account detail. Sensitive account access data is available only from explicit reveal or verification-code operations after their policy and billing checks.","required":["id","platform","username","visible_name","biography","profile_picture_url","country","link_in_bio","profile_url","created_at","updated_at","bundle_id","external_ref","reveal_endpoint","verification_code_endpoint","banned","ban","ban_appeal","remade","managed_subscription"],"properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["tiktok","instagram","youtube"]},"username":{"type":["string","null"]},"visible_name":{"type":["string","null"]},"biography":{"type":["string","null"]},"profile_picture_url":{"type":["string","null"]},"country":{"type":["string","null"]},"link_in_bio":{"type":["string","null"]},"profile_url":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"},"bundle_id":{"type":["string","null"],"format":"uuid"},"external_ref":{"type":["string","null"]},"reveal_endpoint":{"type":"string"},"verification_code_endpoint":{"type":"string"},"banned":{"type":"boolean"},"ban":{"$ref":"#/components/schemas/PublicAccountBan"},"ban_appeal":{"$ref":"#/components/schemas/PublicAccountBanAppeal"},"remade":{"$ref":"#/components/schemas/PublicAccountRemade"},"owning_fee":{"$ref":"#/components/schemas/PublicAccountOwningFee"},"managed_subscription":{"oneOf":[{"$ref":"#/components/schemas/ManagedAccountSubscription"},{"type":"null"}]}},"additionalProperties":false},"AccountListResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicAccountSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"additionalProperties":false},"AccountResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicAccountDetail"}},"additionalProperties":false},"ManagedAccountSubscriptionResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ManagedAccountSubscription"}},"additionalProperties":false},"ManagedAccountSubscriptionCancellationResponse":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"type":"object","required":["ok","subscription_id","saved_account_id","cancelled_at","current_period_end","benefits_ended_at","period_refunded","reactivation_requires_current_period","reactivation_may_be_free_until"],"properties":{"ok":{"type":"boolean","enum":[true]},"subscription_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":"string","format":"uuid"},"cancelled_at":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"benefits_ended_at":{"type":"string","format":"date-time","description":"When Coverage benefits and task access stopped. This is immediate on pause."},"period_refunded":{"type":"boolean","enum":[false],"description":"Coverage periods are never refunded when paused."},"reactivation_requires_current_period":{"type":"boolean","enum":[false],"deprecated":true,"description":"Deprecated compatibility field. Always false; reactivation never adds a separate current period."},"reactivation_may_be_free_until":{"type":["string","null"],"format":"date-time","description":"The current billing period end when a free reactivation window may still exist, otherwise null. Fetch a fresh Coverage quote before acting."}},"additionalProperties":false},{"type":"object","required":["ok","already_cancelled","subscription_id","saved_account_id","cancelled_at"],"properties":{"ok":{"type":"boolean","enum":[true]},"already_cancelled":{"type":"boolean","enum":[true]},"subscription_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":"string","format":"uuid"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"current_period_end":{"type":["string","null"],"format":"date-time"},"reactivation_requires_current_period":{"type":"boolean","enum":[false],"deprecated":true},"reactivation_may_be_free_until":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false}]}},"additionalProperties":false},"ManagedAccountResumedTasks":{"type":"object","required":["videos_rescheduled","warming_sessions_resumed","edit_requests_resumed","ad_code_requests_resumed","comment_tasks_resumed"],"properties":{"videos_rescheduled":{"type":"integer","minimum":0},"warming_sessions_resumed":{"type":"integer","minimum":0},"edit_requests_resumed":{"type":"integer","minimum":0},"ad_code_requests_resumed":{"type":"integer","minimum":0},"comment_tasks_resumed":{"type":"integer","minimum":0}},"additionalProperties":false},"ManagedAccountSubscriptionReactivationResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["ok","subscription_id","saved_account_id","credits_charged","reactivation_was_free","unpaid_periods_paid","period_rate_credits","current_period_start","current_period_end","lock_version","credits_remaining","credit_transaction_id","resumed_tasks"],"properties":{"ok":{"type":"boolean","enum":[true]},"subscription_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":"string","format":"uuid"},"credits_charged":{"type":"integer","minimum":0},"reactivation_was_free":{"type":"boolean"},"unpaid_periods_paid":{"type":"integer","minimum":0},"period_rate_credits":{"type":"integer","minimum":0},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"lock_version":{"type":"integer","minimum":0},"credits_remaining":{"type":"number","minimum":0},"credit_transaction_id":{"type":["string","null"],"format":"uuid","description":"Null when reactivation is free and no credit debit is created."},"resumed_tasks":{"$ref":"#/components/schemas/ManagedAccountResumedTasks"}},"additionalProperties":false}},"additionalProperties":false},"CreditCost":{"type":"object","required":["credits","description","note"],"properties":{"credits":{"type":"integer","minimum":0},"description":{"type":"string"},"note":{"type":"string"}},"additionalProperties":false},"ContractBundleAllowance":{"type":"object","required":["policy_key","applies_at","atomic_with_credit_debit","qualifying_bundle","bundle_limit","consumed","remaining","account_creation_credits","advanced_warming_per_term_credits","coverage_exempt","note"],"properties":{"policy_key":{"type":["string","null"]},"applies_at":{"type":"string","enum":["bundle_creation_checkout"]},"atomic_with_credit_debit":{"type":"boolean","enum":[true]},"qualifying_bundle":{"type":"object","required":["platform","country","new_account_only","bundle_types"],"properties":{"platform":{"type":"string"},"country":{"type":"string"},"new_account_only":{"type":"boolean","enum":[true]},"bundle_types":{"type":"array","items":{"type":"string","enum":["account_only","account_and_videos"]}}},"additionalProperties":false},"bundle_limit":{"type":"integer","minimum":1},"consumed":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0},"account_creation_credits":{"type":"integer","minimum":1},"advanced_warming_per_term_credits":{"type":"integer","minimum":1},"coverage_exempt":{"type":"boolean"},"note":{"type":"string"}},"additionalProperties":false},"CreditCostsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["costs","workspace_pricing","contract_bundle_allowance","owning_fee","pricing_transition","examples"],"properties":{"costs":{"type":"object","required":["account_creation","youtube_account_creation","video_upload","advanced_warming","niche_warming","deep_warming","video_edit","comment_task","sound_volume","repost_url","ad_code","managed_account_subscription","credential_reveal"],"properties":{"account_creation":{"$ref":"#/components/schemas/CreditCost"},"youtube_account_creation":{"type":"object","required":["credits","description","note"],"properties":{"credits":{"type":"integer","enum":[100]},"description":{"type":"string"},"note":{"type":"string"}},"additionalProperties":false},"video_upload":{"$ref":"#/components/schemas/CreditCost"},"advanced_warming":{"allOf":[{"$ref":"#/components/schemas/CreditCost"}],"description":"Advanced Niche Warming, priced per niche target. The only warming product TokPortal sells."},"niche_warming":{"allOf":[{"$ref":"#/components/schemas/CreditCost"}],"deprecated":true,"description":"LEGACY — not offered. Superseded by advanced_warming. The key stays in the response so existing integrations keep parsing; never present it as a purchasable option and never quote it."},"deep_warming":{"allOf":[{"$ref":"#/components/schemas/CreditCost"}],"deprecated":true,"description":"LEGACY — discontinued, new orders are rejected. Superseded by advanced_warming. The key stays in the response so existing integrations keep parsing; never present it as a purchasable option."},"video_edit":{"$ref":"#/components/schemas/CreditCost"},"comment_task":{"$ref":"#/components/schemas/CreditCost"},"sound_volume":{"$ref":"#/components/schemas/CreditCost"},"repost_url":{"$ref":"#/components/schemas/CreditCost"},"ad_code":{"$ref":"#/components/schemas/CreditCost"},"managed_account_subscription":{"$ref":"#/components/schemas/CreditCost"},"credential_reveal":{"allOf":[{"$ref":"#/components/schemas/CreditCost"}],"description":"Informational post-cutoff fallback for an unrevealed saved account. The exact reveal quote is account-specific; obtain it from HTTP 428 or 409 on the selected account's reveal or verification-code endpoint."}},"additionalProperties":false},"workspace_pricing":{"type":"object","required":["cohort","effective_at","transition_active","tokportal_coverage_eligible_for_new_accounts_now"],"properties":{"cohort":{"type":"string","enum":["new_credit_customer","existing_credit_customer"]},"effective_at":{"type":"string","format":"date-time"},"transition_active":{"type":"boolean"},"tokportal_coverage_eligible_for_new_accounts_now":{"type":"boolean"}},"additionalProperties":false},"contract_bundle_allowance":{"oneOf":[{"$ref":"#/components/schemas/ContractBundleAllowance"},{"type":"null"}],"description":"Workspace-specific contractual creation allowance, or null. Read this immediately before bundle creation instead of hardcoding special pricing."},"owning_fee":{"type":"object","required":["requires_admin_approval","minimum_live_accounts","minimum_reveal_ratio","pending_reveal_credits","legacy_usd_per_account_per_30_days","new_agreement_usd_per_account_per_30_days","new_agreement_effective_at","note"],"properties":{"requires_admin_approval":{"type":"boolean","enum":[true]},"minimum_live_accounts":{"type":"integer","enum":[25]},"minimum_reveal_ratio":{"type":"number","enum":[0.25]},"pending_reveal_credits":{"type":"integer","enum":[150]},"legacy_usd_per_account_per_30_days":{"type":"number","enum":[10]},"new_agreement_usd_per_account_per_30_days":{"type":"number","enum":[15]},"new_agreement_effective_at":{"type":"string","format":"date-time","description":"Immutable production PRE-migration cutover returned by the database pricing authority."},"note":{"type":"string"}},"additionalProperties":false},"pricing_transition":{"type":"object","required":["users_without_paid_credit_purchase_before_transition","users_with_paid_credit_purchase_before_transition","managed_account_eligibility_at","managed_account_eligibility_at_deprecated","managed_account_eligibility_note","grandfathering"],"properties":{"users_without_paid_credit_purchase_before_transition":{"type":"object","required":["effective_at","tokportal_coverage_eligible_for_accounts_created_at_or_after","account_creation_credits","advanced_warming_per_term_credits"],"properties":{"effective_at":{"type":"string","format":"date-time","description":"Immutable production PRE-migration cutover captured by the database."},"tokportal_coverage_eligible_for_accounts_created_at_or_after":{"type":"string","format":"date-time","description":"Accounts already present before this database-owned cutoff are permanently grandfathered."},"account_creation_credits":{"type":"integer","enum":[32]},"advanced_warming_per_term_credits":{"type":"integer","enum":[5]}},"additionalProperties":false},"users_with_paid_credit_purchase_before_transition":{"type":"object","required":["effective_at","tokportal_coverage_eligible_for_accounts_created_at_or_after","before_effective_at","after_effective_at"],"properties":{"effective_at":{"type":"string","format":"date-time","enum":["2026-08-14T11:00:00.000Z"]},"tokportal_coverage_eligible_for_accounts_created_at_or_after":{"type":"string","format":"date-time","description":"Global database-owned saved-account cutoff; independent from the workspace action-pricing grace deadline."},"before_effective_at":{"type":"object","required":["account_creation_credits","advanced_warming_per_term_credits"],"properties":{"account_creation_credits":{"type":"integer","enum":[25]},"advanced_warming_per_term_credits":{"type":"integer","enum":[3]}},"additionalProperties":false},"after_effective_at":{"type":"object","required":["account_creation_credits","advanced_warming_per_term_credits"],"properties":{"account_creation_credits":{"type":"integer","enum":[32]},"advanced_warming_per_term_credits":{"type":"integer","enum":[5]}},"additionalProperties":false}},"additionalProperties":false},"managed_account_eligibility_at":{"type":"string","format":"date-time","description":"Immutable production PRE-migration cutoff used for permanent saved-account grandfathering."},"managed_account_eligibility_at_deprecated":{"type":"boolean","enum":[false]},"managed_account_eligibility_note":{"type":"string"},"grandfathering":{"type":"string","description":"Account-level permanent grandfathering for TokPortal Coverage and credential reveal. The saved-account creation cutoff is independent from the workspace action-pricing transition."}},"additionalProperties":false},"examples":{"type":"object","required":["account_only","account_with_10_videos","account_with_10_videos_and_warming","account_with_advanced_warming","account_with_10_videos_and_advanced_warming"],"properties":{"account_only":{"$ref":"#/components/schemas/CreditCostExample"},"account_with_10_videos":{"$ref":"#/components/schemas/CreditCostExample"},"account_with_10_videos_and_warming":{"allOf":[{"$ref":"#/components/schemas/CreditCostExample"}],"description":"1 account + 10 videos + 3 Advanced Niche Warming targets at the workspace's effective per-target rate. The key name is historical; the quote is Advanced Niche Warming, never the legacy niche session."},"account_with_advanced_warming":{"$ref":"#/components/schemas/CreditCostExample"},"account_with_10_videos_and_advanced_warming":{"$ref":"#/components/schemas/CreditCostExample"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"CreditCostExample":{"type":"object","required":["description","total"],"properties":{"description":{"type":"string"},"total":{"type":"integer","minimum":0}},"additionalProperties":false},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, never on the message. One code can be returned by any operation that takes an identifier: DRY_RUN_ID_IN_LIVE_REQUEST (400) means you passed an identifier produced by a dry run to a real call — re-run the creation without the X-TokPortal-Dry-Run header to obtain a real one. Error responses are identical in dry-run and real mode; the X-TokPortal-Dry-Run response header is what tells them apart."},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}},"CredentialRevealNegotiationErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","details"],"properties":{"code":{"type":"string","enum":["CREDENTIALS_ACKNOWLEDGMENT_REQUIRED","CREDENTIAL_REVEAL_QUOTE_CHANGED"]},"message":{"type":"string"},"details":{"type":"object","required":["expected_credit_cost","policy_version","title","summary","disclaimer","acknowledgment","confirm_label"],"properties":{"expected_credit_cost":{"type":"integer","minimum":0},"policy_version":{"type":"string","minLength":1},"title":{"type":"string"},"summary":{"type":"string"},"disclaimer":{"type":"string"},"acknowledgment":{"type":"string"},"confirm_label":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"MeResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","email","credits","api_key"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"full_name":{"type":["string","null"]},"company_name":{"type":["string","null"]},"website":{"type":["string","null"]},"company_niche":{"type":["string","null"]},"organic_strategy":{"type":["string","null"]},"role":{"type":["string","null"]},"country":{"type":["string","null"]},"credits":{"type":"object","required":["balance"],"properties":{"balance":{"type":"number"}}},"subscription":{"type":["object","null"],"additionalProperties":true},"api_key":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}}}},"VerificationCodeResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["account_id","verification_code","source"],"properties":{"account_id":{"type":"string","format":"uuid"},"verification_code":{"type":"string","description":"The 6-digit verification code."},"source":{"type":"string","enum":["email","cached"],"description":"\"email\" when freshly fetched from the TokMail inbox, \"cached\" when no new code was found and the last known code is returned."},"note":{"type":"string","description":"Only present when source is \"cached\"."},"credits_charged":{"type":"integer","minimum":0},"managed_reveal_active":{"type":"boolean"}}}}},"AdCodeRequestResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","nullable":true,"description":"The latest ad code request for the video, or null if none exists.","properties":{"ad_code_request_id":{"type":"string","format":"uuid"},"video_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","accepted","in_review","pending_corrections","finalized","cancelled","expired"],"description":"Lifecycle: pending → in_review (manager submitted the code) → finalized (client confirmed). pending_corrections if a redo was requested."},"platform":{"type":"string","enum":["tiktok","instagram"]},"code":{"type":"string","nullable":true,"description":"The Spark Code. Null until the manager submits it (status in_review) or it is delivered (finalized)."},"note":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"submitted_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true}}}}},"AcknowledgeSupportForfeitRequest":{"type":"object","required":["acknowledge_support_forfeit","policy_version"],"description":"Explicit acceptance of the current versioned credential-reveal policy, its exact charge and its applicable account consequences.","properties":{"acknowledge_support_forfeit":{"type":"boolean","enum":[true],"description":"Set to true to confirm, on behalf of the account owner, acceptance of the exact disclosure identified by policy_version. Required on first credential or verification-code access and ignored after the account has already been revealed."},"policy_version":{"type":"string","minLength":1,"maxLength":120,"description":"The exact current policy version returned in error.details.policy_version by HTTP 428 or 409. A missing version returns 428. A supplied non-empty stale or mismatched version returns CREDENTIAL_REVEAL_QUOTE_CHANGED (409), with the current disclosure and expected_credit_cost, before any debit or reveal."}},"additionalProperties":false},"RevealCredentialsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["account_id","credentials"],"properties":{"account_id":{"type":"string","format":"uuid"},"credentials":{"type":"object","required":["tokmail_email","password"],"properties":{"tokmail_email":{"type":["string","null"],"format":"email"},"password":{"type":["string","null"]},"social_credentials":{"type":["object","null"],"additionalProperties":true}}},"last_verification_code":{"type":["string","null"]},"revealed_at":{"type":"string","format":"date-time"},"already_revealed":{"type":"boolean"},"credits_charged":{"type":"integer","minimum":0},"managed_reveal_active":{"type":"boolean"},"acceptance_id":{"type":["string","null"],"format":"uuid"},"policy_version":{"type":["string","null"]},"notice":{"type":"string"}}}}},"UpdateCurrentUserSettingsRequest":{"type":"object","properties":{"company_name":{"type":["string","null"],"maxLength":120},"website":{"type":["string","null"],"maxLength":300},"company_niche":{"type":["string","null"],"maxLength":300},"organic_strategy":{"type":["string","null"],"maxLength":500}},"minProperties":1,"additionalProperties":false},"UpdateAccountCommentingProfileRequest":{"type":"object","properties":{"niche":{"type":["string","null"],"maxLength":500},"persona":{"type":["string","null"],"maxLength":500},"goal":{"type":["string","null"],"enum":["promotion","awareness","product",null]},"language":{"type":["string","null"],"maxLength":80},"tracked_handles":{"type":["array","null"],"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":120}},"daily_tracking_enabled":{"type":["boolean","null"]}},"minProperties":1,"additionalProperties":false},"UpdateCurrentUserSettingsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"company_name":{"type":["string","null"]},"website":{"type":["string","null"]},"company_niche":{"type":["string","null"]},"organic_strategy":{"type":["string","null"]}}}}},"CreateBundleRequest":{"type":"object","required":["bundle_type"],"properties":{"bundle_type":{"type":"string","enum":["account_only","account_and_videos","videos_only"]},"platform":{"type":"string","enum":["tiktok","instagram"],"default":"tiktok","description":"TikTok or Instagram only. YouTube is priced in getCreditCosts but cannot be ordered: a YouTube bundle is rejected with YOUTUBE_DELAYED."},"country":{"type":"string","minLength":2,"maxLength":5,"description":"Country code exactly as returned by listCountries. Most are ISO-3166-1 alpha-2 (FR, DE, BR), but two are not: the United States is \"USA\" and the United Kingdom is \"UK\". The aliases \"US\" and \"GB\" are accepted and resolved to those. A full country name such as \"United States\" is rejected. Required unless bundle_type is videos_only."},"title":{"type":"string","maxLength":200},"videos_quantity":{"type":"integer","minimum":0,"maximum":500,"default":0},"edits_quantity":{"type":"integer","minimum":0,"maximum":500,"default":0},"wants_niche_warming":{"type":"boolean","default":false,"deprecated":true,"description":"Legacy — kept only for accounts being re-created after a refund; use Advanced Niche Warming (wants_advanced_warming)."},"wants_deep_warming":{"type":"boolean","default":false,"deprecated":true,"description":"Legacy — kept only for accounts being re-created after a refund; use Advanced Niche Warming (wants_advanced_warming)."},"wants_advanced_warming":{"type":"boolean","default":false,"description":"Advanced Niche Warming, the warming product: niche-target (search-term) based warming with recorded proof and a data report. MANDATORY whenever you send advanced_warming_terms or advanced_warming_terms_count — TokPortal never infers it, and sending targets without it is rejected with ADVANCED_WARMING_FLAG_REQUIRED rather than charged and dropped. The standard rate is 5 credits per target (per target, never per day); GET /credit-costs returns the effective rate. TikTok and Instagram only. Provide advanced_warming_terms now, or advanced_warming_terms_count to configure the targets later."},"advanced_warming_terms":{"type":"array","minItems":3,"maxItems":30,"x-item-count-multiple-of":3,"items":{"type":"string","minLength":2,"maxLength":50},"description":"3-30 niche targets (search terms), count a multiple of 3, each 2-50 characters. REQUIRES wants_advanced_warming: true in the same body (ADVANCED_WARMING_FLAG_REQUIRED otherwise). Every term must survive cleanup intact: entries are trimmed and compared case-insensitively, and if any is dropped as a duplicate or for its length the call fails with ADVANCED_WARMING_TERMS_REJECTED listing what was dropped — TokPortal will not quietly deliver, or bill, fewer targets than you asked for. Send this list OR advanced_warming_terms_count, not both: a count that disagrees with the list length fails with ADVANCED_WARMING_COUNT_MISMATCH."},"advanced_warming_terms_count":{"type":"integer","minimum":3,"maximum":30,"multipleOf":3,"x-value-multiple-of":3,"description":"Number of niche targets to purchase (3-30, multiples of 3; standard rate 5 credits each; GET /credit-costs returns the effective rate); the alternative to advanced_warming_terms when the targets are not decided yet. REQUIRES wants_advanced_warming: true in the same body (ADVANCED_WARMING_FLAG_REQUIRED otherwise). Do not send it alongside advanced_warming_terms unless it equals that list's length — a disagreement fails with ADVANCED_WARMING_COUNT_MISMATCH instead of one quantity silently winning. Configure the targets later via PUT /bundles/{id}/warming-terms — but BEFORE publishing: publishBundle refuses a bundle whose warming has no targets (ADVANCED_WARMING_NOT_CONFIGURED), because a warming that can never start also stops the bundle from ever completing. A purchase left unconfigured is not refunded."},"niche_warming_instructions":{"type":"string","maxLength":2000,"deprecated":true,"description":"Legacy — kept only for accounts being re-created after a refund; use Advanced Niche Warming (wants_advanced_warming)."},"auto_finalize_videos":{"type":"boolean","default":true,"description":"Defaults to true: delivered videos are approved automatically and count as final. Set false to hold each delivered video for your manual review (approve or request corrections). Changeable later via updateBundle."},"account_id":{"type":"string","format":"uuid","description":"The single delivered account a videos_only bundle posts to. Required for videos_only bundles, forbidden otherwise. One bundle targets exactly one account — to post across several accounts, create one bundle per account."},"external_ref":{"type":"string","maxLength":200,"description":"Optional client correlation reference and duplicate-detection aid for new-account bundles. Reusing it can return DUPLICATE_ACCOUNT_BUNDLE. It does not provide request retry or response replay; use Idempotency-Key for that."}},"dependentRequired":{"advanced_warming_terms":["wants_advanced_warming"],"advanced_warming_terms_count":["wants_advanced_warming"]},"not":{"required":["wants_niche_warming","wants_advanced_warming"],"properties":{"wants_niche_warming":{"const":true},"wants_advanced_warming":{"const":true}}},"additionalProperties":false},"PatchBundleRequest":{"type":"object","properties":{"auto_finalize_videos":{"type":"boolean"},"external_ref":{"type":["string","null"],"maxLength":200},"title":{"type":["string","null"],"maxLength":200}},"minProperties":1,"additionalProperties":false},"CreateBundleResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"required":["bundle_id","status","review_mode"],"properties":{"bundle_id":{"type":"string","format":"uuid"},"bundle_type":{"type":"string","enum":["account_only","account_and_videos","videos_only"]},"platform":{"type":"string"},"country":{"type":["string","null"]},"status":{"type":"string","enum":["pending_setup"]},"videos_quantity":{"type":["integer","null"]},"edits_quantity":{"type":["integer","null"]},"wants_advanced_warming":{"type":"boolean"},"advanced_warming_terms":{"type":"array","items":{"type":"string"}},"advanced_warming_terms_count":{"type":["integer","null"]},"external_ref":{"type":["string","null"]},"review_mode":{"type":"string","enum":["auto","manual"],"description":"How delivered videos are settled for this bundle. 'auto' (the default when auto_finalize_videos is omitted) approves every delivered video automatically — it counts as final on arrival. 'manual' holds each delivery for your review so you approve with finalizeBundleVideo or push back with requestBundleVideoCorrections; anything still in review is auto-finalized about 72 hours later either way. Changeable at any time with updateBundle."},"review_mode_notice":{"type":"string","description":"Present ONLY when the request omitted auto_finalize_videos, to state that the default (auto) was applied and how to opt into manual review. It disappears as soon as the caller sends the field explicitly, so its presence means 'you did not choose', not 'something went wrong'."},"created_at":{"type":"string","format":"date-time"}}},"credits_charged":{"type":"number","description":"Credits debited by this call. Always 0 on a dry run."},"credits_remaining":{"type":"number"},"cost_breakdown":{"type":"object","additionalProperties":true},"dry_run":{"type":"boolean","enum":[true],"description":"Present ONLY when the call was simulated via the X-TokPortal-Dry-Run header. Nothing was created and nothing was debited; the identifiers in `data` are synthetic. Absent — never false — on a real call."},"dry_run_notice":{"type":"string","description":"Plain-sentence restatement of what a dry run did and did not do, for an agent to relay to a human. Present only alongside `dry_run`."},"credits_would_charge":{"type":"number","description":"Dry runs only: the real server-side price this call would have cost, allowance included. This is the number to confirm with a human before repeating the call for real. On a real call the equivalent is `credits_charged`."}}},"CreateBulkBundlesResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"required":["bundles_created","bundles","review_mode"],"properties":{"bundles_created":{"type":"integer"},"bundles":{"type":"array","items":{"type":"object","additionalProperties":true}},"review_mode":{"type":"string","enum":["auto","manual"],"description":"How delivered videos are settled for this bundle. 'auto' (the default when auto_finalize_videos is omitted) approves every delivered video automatically — it counts as final on arrival. 'manual' holds each delivery for your review so you approve with finalizeBundleVideo or push back with requestBundleVideoCorrections; anything still in review is auto-finalized about 72 hours later either way. Changeable at any time with updateBundle."},"review_mode_notice":{"type":"string","description":"Present ONLY when the request omitted auto_finalize_videos, to state that the default (auto) was applied and how to opt into manual review. It disappears as soon as the caller sends the field explicitly, so its presence means 'you did not choose', not 'something went wrong'."},"summary":{"type":"object","additionalProperties":true}}},"batch_id":{"type":"string"},"credits_charged":{"type":"number","description":"Credits debited by this call. Always 0 on a dry run."},"credits_remaining":{"type":"number"},"cost_breakdown":{"type":"object","additionalProperties":true},"dry_run":{"type":"boolean","enum":[true],"description":"Present ONLY when the call was simulated via the X-TokPortal-Dry-Run header. Nothing was created and nothing was debited; the identifiers in `data` are synthetic. Absent — never false — on a real call."},"dry_run_notice":{"type":"string","description":"Plain-sentence restatement of what a dry run did and did not do, for an agent to relay to a human. Present only alongside `dry_run`."},"credits_would_charge":{"type":"number","description":"Dry runs only: the real server-side price this call would have cost, allowance included. This is the number to confirm with a human before repeating the call for real. On a real call the equivalent is `credits_charged`."}}},"CreateBulkBundlesRequest":{"type":"object","required":["platforms","country","accounts_count"],"properties":{"platforms":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["tiktok","instagram"]},"description":"TikTok and/or Instagram. accounts_count accounts are created on EACH listed platform, so the batch total is accounts_count x platforms.length. YouTube cannot be ordered (YOUTUBE_DELAYED)."},"country":{"type":"string","minLength":2,"maxLength":5,"description":"Country code exactly as returned by listCountries. Most are ISO-3166-1 alpha-2 (FR, DE, BR), but two are not: the United States is \"USA\" and the United Kingdom is \"UK\". The aliases \"US\" and \"GB\" are accepted and resolved to those. A full country name such as \"United States\" is rejected. videos_only_countries is never valid here."},"accounts_count":{"type":"integer","minimum":1,"maximum":100,"description":"Accounts to create per platform. Each one is a separate bundle with its own account, and every credit below is charged per account."},"upload_accounts_count":{"type":"integer","minimum":0,"maximum":100,"default":0},"videos_per_account":{"type":"integer","minimum":0,"maximum":500,"default":0},"wants_niche_warming":{"type":"boolean","default":false,"deprecated":true,"description":"Legacy — kept only for accounts being re-created after a refund; use Advanced Niche Warming (wants_advanced_warming)."},"wants_deep_warming":{"type":"boolean","default":false,"deprecated":true,"description":"Legacy — kept only for accounts being re-created after a refund; use Advanced Niche Warming (wants_advanced_warming)."},"wants_advanced_warming":{"type":"boolean","default":false,"description":"Advanced Niche Warming, the warming product: niche-target (search-term) based warming with recorded proof and a data report. MANDATORY whenever you send advanced_warming_terms or advanced_warming_terms_count — TokPortal never infers it, and sending targets without it is rejected with ADVANCED_WARMING_FLAG_REQUIRED rather than charged and dropped. The standard rate is 5 credits per target (per target, never per day), charged per account; GET /credit-costs returns the effective rate. TikTok and Instagram only. Provide advanced_warming_terms now, or advanced_warming_terms_count to configure the targets later."},"advanced_warming_terms":{"type":"array","minItems":3,"maxItems":30,"x-item-count-multiple-of":3,"items":{"type":"string","minLength":2,"maxLength":50},"description":"3-30 niche targets (search terms), count a multiple of 3, each 2-50 characters, applied identically to every account of the batch. REQUIRES wants_advanced_warming: true in the same body (ADVANCED_WARMING_FLAG_REQUIRED otherwise). Every term must survive cleanup intact: entries are trimmed and compared case-insensitively, and if any is dropped as a duplicate or for its length the call fails with ADVANCED_WARMING_TERMS_REJECTED listing what was dropped. Send this list OR advanced_warming_terms_count, not both: a count that disagrees with the list length fails with ADVANCED_WARMING_COUNT_MISMATCH."},"advanced_warming_terms_count":{"type":"integer","minimum":3,"maximum":30,"multipleOf":3,"x-value-multiple-of":3,"description":"Number of niche targets purchased PER ACCOUNT (3-30, multiples of 3; standard rate 5 credits each; GET /credit-costs returns the effective rate); the alternative to advanced_warming_terms when the targets are not decided yet. REQUIRES wants_advanced_warming: true in the same body (ADVANCED_WARMING_FLAG_REQUIRED otherwise). Do not send it alongside advanced_warming_terms unless it equals that list's length — a disagreement fails with ADVANCED_WARMING_COUNT_MISMATCH. Configure each bundle's targets later via PUT /bundles/{id}/warming-terms — but BEFORE publishing: publishBundle refuses a bundle whose warming has no targets (ADVANCED_WARMING_NOT_CONFIGURED). A purchase left unconfigured is not refunded."},"niche_warming_instructions":{"type":"string","maxLength":2000,"deprecated":true,"description":"Legacy — kept only for accounts being re-created after a refund; use Advanced Niche Warming (wants_advanced_warming)."},"auto_finalize_videos":{"type":"boolean","default":true,"description":"Defaults to true: delivered videos are approved automatically and count as final. Set false to hold each delivered video for your manual review (approve or request corrections). Changeable later via updateBundle."},"external_ref":{"type":"string","maxLength":200,"description":"Optional batch-level client reference copied to every bundle created by this call. It is not unique per resulting bundle and is not an idempotency key. Use the returned bundle IDs for per-bundle identity and Idempotency-Key for retry/replay."}},"dependentRequired":{"advanced_warming_terms":["wants_advanced_warming"],"advanced_warming_terms_count":["wants_advanced_warming"]},"not":{"required":["wants_niche_warming","wants_advanced_warming"],"properties":{"wants_niche_warming":{"const":true},"wants_advanced_warming":{"const":true}}},"additionalProperties":false},"ConfigureAccountRequest":{"type":"object","required":["username","visible_name"],"properties":{"username":{"type":"string","minLength":1,"maxLength":24,"pattern":"^[a-zA-Z0-9_.]+$","description":"Requested username. Cannot end with a dot."},"visible_name":{"type":"string","minLength":1,"maxLength":30,"description":"Public display name. Avoid reusing the same wording across accounts of one batch: near-identical profiles raise the risk of mass-ban detection."},"biography":{"type":"string","maxLength":120,"description":"Profile biography. The enforced limit is platform-dependent: 120 characters on Instagram, 80 on every other platform."},"profile_picture_url":{"type":"string","description":"Public image URL, or the storage_path returned by uploadImage / uploadImageDirect / uploadImageFromUrl. Use storage_path, not public_url — public_url is only correct for videos."},"link_in_bio":{"type":"string","format":"uri","description":"Instagram bundles only. On TikTok and every other platform it is accepted, stored as null, and reported back in the response's _warnings array — read _warnings, not just the 200."},"niche_warming_instructions":{"type":"string","maxLength":2000,"deprecated":true,"description":"Legacy — kept only for accounts being re-created after a refund; use Advanced Niche Warming (wants_advanced_warming)."},"advanced_warming_terms":{"type":"array","minItems":3,"maxItems":30,"x-item-count-multiple-of":3,"items":{"type":"string","minLength":2,"maxLength":50},"description":"Backward-compatible account-configuration field for an Advanced Niche Warming purchase made with advanced_warming_terms_count. Prefer PUT /bundles/{id}/warming-terms, which remains available at any account status. Must contain exactly the purchased number of targets and can only be set once."}},"additionalProperties":false},"ConfigureVideoRequest":{"type":"object","required":["video_type","target_publish_date"],"properties":{"video_type":{"type":"string","enum":["video","carousel","story"]},"description":{"type":"string","minLength":1,"maxLength":2200,"description":"Required for 'video' and 'carousel'. Stories have no description."},"target_publish_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD. This is the FIRST day of a 2-day publishing window, not a fixed date: the manager may post on this day or the next. The end day is derived — always this day + 1 — and cannot be chosen here; sending target_publish_end_date is rejected. Every video response returns the resulting window as target_publish_start_date / target_publish_end_date (target_publish_date is an alias of the start). Max 3 videos per day per bundle — a 4th video on the same day is rejected with VIDEOS_PER_DAY_EXCEEDED. Minimum lead time, in UTC: the earliest allowed date is today+3 days while the bundle is still having its account created, and today+1 once that account is delivered or when the bundle runs on an existing account; an earlier date is rejected with INVALID_DATE carrying min_days_ahead and earliest_allowed (YYYY-MM-DD)."},"name":{"type":"string","maxLength":200},"video_url":{"type":"string","format":"uri","description":"Required for video_type 'video'. Use the public_url returned by uploadVideo / uploadVideoDirect (videos use public_url; images use storage_path)."},"carousel_images":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"uri"},"description":"Required for video_type 'carousel'. Use the storage_path returned by the image upload tools, NOT public_url (public_url is only correct for videos)."},"carousel_title":{"type":"string","maxLength":200},"story_image_url":{"type":"string","format":"uri","description":"Story image (TikTok/Instagram). Provide exactly one of video_url or story_image_url for a story."},"story_repost_url":{"type":"string","format":"uri","description":"Optional. Make the story repost an existing post from the SAME platform (TikTok story → tiktok.com, Instagram story → instagram.com). Costs +1 credit."},"tiktok_sound_url":{"type":"string","format":"uri","description":"TikTok bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields. REQUIRED for a TikTok carousel (MISSING_FIELD otherwise), optional for a TikTok video."},"volume_original_sound":{"type":["integer","null"],"minimum":0,"maximum":200,"description":"Playback volume of the clip's own audio, as a percentage; 100 leaves it unchanged. PAID OPTION: setting either volume field costs +1 credit per video, charged once when it is first set and never refunded."},"volume_added_sound":{"type":["integer","null"],"minimum":0,"maximum":200,"description":"Playback volume of the added sound, as a percentage; 100 leaves it unchanged. PAID OPTION: setting either volume field costs +1 credit per video, charged once when it is first set and never refunded."},"editing_instructions":{"type":"string","maxLength":5000},"external_ref":{"type":"string","maxLength":200},"instagram_content_type":{"type":"string","enum":["reel","post"],"description":"REQUIRED for every Instagram slot that is not a story (MISSING_FIELD otherwise). Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"instagram_location":{"type":"string","maxLength":200,"description":"Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"instagram_collaborators":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"instagram_audio_name":{"type":"string","maxLength":200,"description":"Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"instagram_add_to_story":{"type":"boolean","description":"Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"ai_content_disclaimer":{"type":"boolean","description":"AI content notice (free). If true, the manager will enable the platform's AI-generated content label when posting."},"disclose_as_ads":{"type":"boolean","description":"Disclose as ad (free). If true, the manager will enable branded-content/paid-partnership disclosure (or add #ad) when posting."},"instant_repost_as_story":{"type":"boolean","description":"Instant repost as story (paid, +1 credit charged once when first enabled, no refunds). Right after posting, the manager reposts this video as a story and provides a screenshot proof. Only for video_type 'video' on TikTok/Instagram bundles. Omit to keep the current value."},"youtube_title":{"type":"string","maxLength":200,"description":"YouTube bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields. YouTube bundles cannot currently be created (YOUTUBE_DELAYED)."},"youtube_tags":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"YouTube bundles only. Elsewhere it is accepted but not stored, and comes back in the response's ignored_fields."},"youtube_category":{"type":"string","maxLength":100,"description":"YouTube bundles only. Elsewhere it is accepted but not stored, and comes back in the response's ignored_fields."},"youtube_visibility":{"type":"string","enum":["public","unlisted","private"],"description":"YouTube bundles only. Elsewhere it is accepted but not stored, and comes back in the response's ignored_fields."},"youtube_sound_url":{"type":"string","format":"uri","description":"YouTube bundles only. Elsewhere it is accepted but not stored, and comes back in the response's ignored_fields."},"auto_publish":{"type":"boolean","default":false,"description":"PER-VIDEO on this single-slot endpoint: it publishes this one slot in the same call. On the batch endpoint the same flag exists only at the ROOT of the body and covers every video in the call — it is not accepted inside videos[]. A publish failure never fails the configuration: the response carries auto_publish.published and auto_publish.blockers, so read them instead of assuming the slot went live. If publishing moved a stale target date forward, auto_publish.adjusted_videos lists {video_id, position, previous_date, new_date} — read it back rather than assuming the schedule you sent survived."}},"additionalProperties":false},"PatchVideoRequest":{"type":"object","properties":{"external_ref":{"type":["string","null"],"maxLength":200},"name":{"type":["string","null"],"maxLength":200},"description":{"type":["string","null"],"maxLength":2200},"target_publish_date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD. Shorthand for a 2-day window: the end day is derived as this day + 1. Max 3 videos per day per bundle — a 4th video on the same day is rejected with VIDEOS_PER_DAY_EXCEEDED. Minimum lead time, in UTC: the earliest allowed date is today+3 days while the bundle is still having its account created, and today+1 once that account is delivered or when the bundle runs on an existing account; an earlier date is rejected with INVALID_DATE carrying min_days_ahead and earliest_allowed (YYYY-MM-DD). Cannot be combined with target_publish_start_date / target_publish_end_date."},"target_publish_start_date":{"type":["string","null"],"format":"date-time","description":"Start of the publication window as an ISO 8601 date-time; only its UTC calendar day is kept. The window is always the same 2-day window as everywhere else: that day at 00:00 UTC and the next day — the end is derived and can never be shortened or extended (any time-of-day or caller-supplied end is normalized away; the response returns the stored window). Prefer target_publish_date (YYYY-MM-DD); never send both. Since 2026-08-26 it obeys the same minimum lead time as configuration (today+1 with a delivered or existing account, today+3 while the account is still being created, in UTC); an earlier value is rejected with INVALID_DATE carrying min_days_ahead and earliest_allowed."},"target_publish_end_date":{"type":["string","null"],"format":"date-time","description":"Accepted for backward compatibility only. Must be strictly after target_publish_start_date and sent together with it — never alongside target_publish_date, and never on the configuration or CSV endpoints, where this field is refused. It does not choose the window: the end day is always the start day + 1 (2026-09-05), and the response returns the stored window."}},"minProperties":1,"additionalProperties":false},"BatchConfigureVideosRequest":{"type":"object","required":["videos"],"properties":{"videos":{"type":"array","minItems":1,"maxItems":500,"description":"Slots to configure. Each entry is validated and applied independently: the call answers HTTP 200 even when some or all entries fail, so read configured, results and errors[] rather than the status code.","items":{"type":"object","required":["video_type","target_publish_date","position"],"properties":{"video_type":{"type":"string","enum":["video","carousel","story"]},"description":{"type":"string","minLength":1,"maxLength":2200,"description":"Required for 'video' and 'carousel'. Stories have no description."},"target_publish_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"YYYY-MM-DD. This is the FIRST day of a 2-day publishing window, not a fixed date: the manager may post on this day or the next. The end day is derived — always this day + 1 — and cannot be chosen here; sending target_publish_end_date is rejected. Every video response returns the resulting window as target_publish_start_date / target_publish_end_date (target_publish_date is an alias of the start). Max 3 videos per day per bundle — a 4th video on the same day is rejected with VIDEOS_PER_DAY_EXCEEDED. Minimum lead time, in UTC: the earliest allowed date is today+3 days while the bundle is still having its account created, and today+1 once that account is delivered or when the bundle runs on an existing account; an earlier date is rejected with INVALID_DATE carrying min_days_ahead and earliest_allowed (YYYY-MM-DD)."},"name":{"type":"string","maxLength":200},"video_url":{"type":"string","format":"uri","description":"Required for video_type 'video'. Use the public_url returned by uploadVideo / uploadVideoDirect (videos use public_url; images use storage_path)."},"carousel_images":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"uri"},"description":"Required for video_type 'carousel'. Use the storage_path returned by the image upload tools, NOT public_url (public_url is only correct for videos)."},"carousel_title":{"type":"string","maxLength":200},"story_image_url":{"type":"string","format":"uri","description":"Story image (TikTok/Instagram). Provide exactly one of video_url or story_image_url for a story."},"story_repost_url":{"type":"string","format":"uri","description":"Optional. Make the story repost an existing post from the SAME platform (TikTok story → tiktok.com, Instagram story → instagram.com). Costs +1 credit."},"tiktok_sound_url":{"type":"string","format":"uri","description":"TikTok bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields. REQUIRED for a TikTok carousel (MISSING_FIELD otherwise), optional for a TikTok video."},"volume_original_sound":{"type":["integer","null"],"minimum":0,"maximum":200,"description":"Playback volume of the clip's own audio, as a percentage; 100 leaves it unchanged. PAID OPTION: setting either volume field costs +1 credit per video, charged once when it is first set and never refunded."},"volume_added_sound":{"type":["integer","null"],"minimum":0,"maximum":200,"description":"Playback volume of the added sound, as a percentage; 100 leaves it unchanged. PAID OPTION: setting either volume field costs +1 credit per video, charged once when it is first set and never refunded."},"editing_instructions":{"type":"string","maxLength":5000},"external_ref":{"type":"string","maxLength":200},"instagram_content_type":{"type":"string","enum":["reel","post"],"description":"REQUIRED for every Instagram slot that is not a story (MISSING_FIELD otherwise). Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"instagram_location":{"type":"string","maxLength":200,"description":"Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"instagram_collaborators":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"instagram_audio_name":{"type":"string","maxLength":200,"description":"Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"instagram_add_to_story":{"type":"boolean","description":"Instagram bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields."},"ai_content_disclaimer":{"type":"boolean","description":"AI content notice (free). If true, the manager will enable the platform's AI-generated content label when posting."},"disclose_as_ads":{"type":"boolean","description":"Disclose as ad (free). If true, the manager will enable branded-content/paid-partnership disclosure (or add #ad) when posting."},"instant_repost_as_story":{"type":"boolean","description":"Instant repost as story (paid, +1 credit charged once when first enabled, no refunds). Right after posting, the manager reposts this video as a story and provides a screenshot proof. Only for video_type 'video' on TikTok/Instagram bundles. Omit to keep the current value."},"youtube_title":{"type":"string","maxLength":200,"description":"YouTube bundles only. On any other platform it is accepted but not stored, and comes back in the response's ignored_fields. YouTube bundles cannot currently be created (YOUTUBE_DELAYED)."},"youtube_tags":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"YouTube bundles only. Elsewhere it is accepted but not stored, and comes back in the response's ignored_fields."},"youtube_category":{"type":"string","maxLength":100,"description":"YouTube bundles only. Elsewhere it is accepted but not stored, and comes back in the response's ignored_fields."},"youtube_visibility":{"type":"string","enum":["public","unlisted","private"],"description":"YouTube bundles only. Elsewhere it is accepted but not stored, and comes back in the response's ignored_fields."},"youtube_sound_url":{"type":"string","format":"uri","description":"YouTube bundles only. Elsewhere it is accepted but not stored, and comes back in the response's ignored_fields."},"position":{"type":"integer","minimum":1,"description":"1-based slot position on the bundle. Required on every entry."}},"additionalProperties":false}},"auto_publish":{"type":"boolean","default":false,"description":"Publish the bundle in the same call once at least one row has been configured. TOP-LEVEL ONLY on this endpoint: one publish attempt per call, applying to every video in it. auto_publish inside videos[] is rejected with a hint telling you to move it out — it is per-video only on the single-slot PUT /bundles/{id}/videos/{position}. A publish failure never fails the configuration: read auto_publish.published and auto_publish.blockers. If publishing moved stale target dates forward, auto_publish.adjusted_videos lists {video_id, position, previous_date, new_date}."}},"additionalProperties":false},"QuantityRequest":{"type":"object","required":["quantity"],"properties":{"quantity":{"type":"integer","minimum":1,"maximum":500,"description":"How many slots to buy. Charged immediately at the getCreditCosts rate and never refundable — there is no cancellation path for this purchase."}},"additionalProperties":false},"AccountEditRequest":{"type":"object","required":["requested_username","requested_visible_name"],"properties":{"requested_username":{"type":"string","minLength":1,"maxLength":24,"description":"Requested username. Always required, even when it is unchanged."},"requested_visible_name":{"type":"string","minLength":1,"maxLength":30,"description":"Requested display name. Always required, even when it is unchanged."},"requested_biography":{"type":"string","maxLength":150,"description":"Requested biography. The enforced limit is platform-dependent: 150 characters on Instagram, 80 on every other platform."},"requested_profile_picture_url":{"type":"string","description":"Public image URL, or the storage_path returned by the image upload tools (not public_url)."},"requested_link_in_bio":{"type":"string","format":"uri"}},"anyOf":[{"required":["requested_biography"]},{"required":["requested_profile_picture_url"]},{"required":["requested_link_in_bio"]}],"additionalProperties":false},"AdCodeRequest":{"type":"object","properties":{"note":{"type":"string","maxLength":500,"description":"Optional note to your manager (e.g. the campaign this ad code is for)."}},"additionalProperties":false},"RewarmAccountRequest":{"type":"object","required":["search_terms"],"properties":{"search_terms":{"type":"array","minItems":3,"maxItems":30,"x-item-count-multiple-of":3,"items":{"type":"string","minLength":2,"maxLength":50},"description":"3-30 search terms, and the count MUST be a multiple of 3 (3, 6, 9 … 30), each 2-50 characters. The standard rate is 5 credits per term (per target, never per day); GET /credit-costs returns the effective rate. For each term the manager screen-records a session that opens on the account profile, searches the term, watches videos from the results, engages with them (likes/saves) and leaves a comment. Every recording is verified before the manager is paid."}},"additionalProperties":false},"ConfigureWarmingTermsRequest":{"type":"object","required":["advanced_warming_terms"],"properties":{"advanced_warming_terms":{"type":"array","minItems":3,"maxItems":30,"x-item-count-multiple-of":3,"items":{"type":"string","minLength":2,"maxLength":50},"description":"The niche targets for a count-only Advanced Niche Warming purchase. Must contain EXACTLY the purchased number of targets (advanced_warming_terms_count at creation), each 2-50 characters. One-shot: once set they cannot be changed. This works at any account status, and the warming session starts immediately when the manager already holds the order."}},"additionalProperties":false},"GenerateWarmingTermsRequest":{"type":"object","required":["text","platform","count"],"properties":{"text":{"type":"string","minLength":1,"maxLength":1000,"description":"Free-text description of the account's niche/brand (max 1000 characters). Terms are generated in the same language."},"platform":{"type":"string","enum":["tiktok","instagram"],"description":"Platform the terms will be searched on."},"count":{"type":"integer","minimum":3,"maximum":30,"multipleOf":3,"x-value-multiple-of":3,"description":"Desired number of terms: 3-30, must be a multiple of 3."}},"additionalProperties":false},"WarmingSessionResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["session_id","status","terms_total","tasks"],"properties":{"session_id":{"type":"string","format":"uuid"},"account_id":{"type":["string","null"],"format":"uuid","description":"Saved account being warmed (null for bundle-sourced sessions before delivery)."},"bundle_id":{"type":["string","null"],"format":"uuid"},"order_id":{"type":["string","null"],"format":"uuid"},"source":{"type":"string","enum":["bundle","rewarm"],"description":"'bundle' = ordered with wants_advanced_warming at bundle creation; 'rewarm' = ordered later via POST /accounts/{id}/rewarm."},"platform":{"type":"string","enum":["tiktok","instagram"]},"status":{"type":"string","enum":["pending","in_progress","completed","expired","cancelled"]},"search_terms":{"type":"array","items":{"type":"string"},"description":"The niche targets. EMPTY while a count-only purchase (advanced_warming_terms_count) has not been configured yet via PUT /bundles/{id}/warming-terms."},"terms_total":{"type":"integer"},"terms_verified":{"type":"integer"},"credits_cost":{"type":"integer"},"refunded_credits":{"type":"integer","description":"Credits refunded per target that expired unfinished, or for the full purchase when a count-only session was never configured within 14 days (session becomes 'cancelled')."},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"report":{"type":["object","null"],"additionalProperties":true,"description":"Aggregated client report (per-term details + engagement totals). Null until the session completes."},"tasks":{"type":"array","items":{"type":"object","required":["id","term","day_index","status"],"properties":{"id":{"type":"string","format":"uuid"},"term":{"type":"string"},"day_index":{"type":"integer","minimum":1,"maximum":3,"description":"Warming day (1-3) the term is dispatched to."},"status":{"type":"string","enum":["pending","submitted","verified","rejected","expired"]},"verified_at":{"type":["string","null"],"format":"date-time"},"report":{"type":["object","null"],"additionalProperties":true,"description":"Client-facing per-term report (videos watched, likes, saves, comment, sample content). Null until verified."},"proof_video_url":{"type":["string","null"],"format":"uri"}}}},"created_at":{"type":"string","format":"date-time"}}}}},"AccountCorrectionsRequest":{"type":"object","required":["comment"],"properties":{"comment":{"type":"string","minLength":1,"maxLength":2000},"fields":{"type":"object","properties":{"username":{"type":"boolean"},"visible_name":{"type":"boolean"},"biography":{"type":"boolean"},"profile_picture":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"VideoCorrectionsRequest":{"type":"object","required":["comment"],"properties":{"comment":{"type":"string","minLength":1,"maxLength":2000},"fields":{"type":"object","properties":{"video_content":{"type":"boolean"},"description":{"type":"boolean"},"video_editing":{"type":"boolean"},"sound":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false},"FixVideoDownloadRequest":{"type":"object","properties":{"video_url":{"type":"string","format":"uri"},"carousel_images":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"uri"}}},"anyOf":[{"required":["video_url"]},{"required":["carousel_images"]}],"additionalProperties":false},"RefreshAnalyticsRequest":{"type":"object","properties":{"force":{"type":"boolean","default":false,"description":"Bypass the recent-snapshot dedup. Without it the call can return 200 with deduped: true and skippedReason: \"recent_snapshot\", meaning nothing was refreshed. A forced refresh consumes the manual-refresh cooldown slot (6 h connected / 24 h public); check canRefreshAccountAnalytics first."},"includePosts":{"type":"boolean","default":true},"includeComments":{"type":"boolean","default":false,"description":"Only takes effect when force is true AND includePosts is not false AND the workspace holds the full analytics tier. The two conditions you control are enforced: sending it without force, or with includePosts false, fails with INVALID_FIELD for MCP callers and is reported for direct REST callers. The tier condition, which you cannot control, is reported on the response as applied.include_comments with applied.include_comments_dropped_reason and applied.analytics_tier. Read applied rather than assuming a 200 means comments were imported."},"forcePosts":{"type":"boolean","default":false},"bootstrapPosts":{"type":"boolean","default":false},"postLimit":{"type":"integer","minimum":1,"maximum":60,"default":20}},"additionalProperties":false},"CommentTask":{"type":"object","required":["id","status","platform","saved_account_id","target_type","target_video_url","target_comment_url","target_comment_id","target_author_handle","comment_text","cm_payout_amount","verified_at","submitted_at","manually_confirmed_at","client_dispute_deadline_at","finalized_at","correction_required","deadline_at","execution_blocked","execution_blocked_at","execution_block_reason","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","submitted","verified_auto","needs_review","rejected","finalized","cancelled","pending_corrections","manually_confirmed"]},"platform":{"type":"string","enum":["tiktok","instagram","youtube"],"description":"Task platform. New comment tasks support TikTok and Instagram; YouTube can appear on historical reads."},"saved_account_id":{"type":"string","format":"uuid"},"target_type":{"type":"string","enum":["video","comment"]},"target_video_url":{"type":"string","format":"uri"},"target_comment_url":{"type":["string","null"],"format":"uri"},"target_comment_id":{"type":["string","null"]},"target_author_handle":{"type":["string","null"]},"comment_text":{"type":"string"},"cm_payout_amount":{"type":"number","minimum":0},"verified_at":{"type":["string","null"],"format":"date-time"},"submitted_at":{"type":["string","null"],"format":"date-time"},"manually_confirmed_at":{"type":["string","null"],"format":"date-time"},"client_dispute_deadline_at":{"type":["string","null"],"format":"date-time"},"finalized_at":{"type":["string","null"],"format":"date-time"},"correction_required":{"type":["string","null"]},"deadline_at":{"type":"string","format":"date-time"},"execution_blocked":{"type":"boolean","description":"True when inactive TokPortal Coverage currently prevents manager execution. This does not change the task's durable workflow status."},"execution_blocked_at":{"type":["string","null"],"format":"date-time"},"execution_block_reason":{"type":["string","null"],"description":"Stable Coverage reason such as managed_subscription_lapsed or managed_subscription_cancelled. Fetch GET /accounts/{saved_account_id}/managed-subscription for recovery details."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"CommentTaskResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CommentTask"}},"additionalProperties":false},"CommentTaskListResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommentTask"}},"pagination":{"type":"object","required":["page","per_page","total","total_pages"],"properties":{"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0},"total_pages":{"type":"integer","minimum":0}},"additionalProperties":false}},"additionalProperties":false},"CreateCommentTasksResponse":{"type":"object","required":["data","created_count","rejected_count","credits_charged"],"properties":{"data":{"type":"object","required":["created","rejected"],"properties":{"created":{"type":"array","items":{"$ref":"#/components/schemas/CommentTask"}},"rejected":{"type":"array","description":"Rows that were not created and were not charged. Retry only recoverable rows with a new logical request.","items":{"type":"object","required":["reason","raw"],"properties":{"reason":{"type":"string","description":"Stable row reason, including inactive Coverage reasons such as managed_subscription_lapsed or managed_subscription_cancelled."},"raw":{"type":"object","required":["saved_account_id","target_type","target_video_url","target_comment_url"],"properties":{"saved_account_id":{"type":"string","format":"uuid"},"target_type":{"type":"string","enum":["video","comment"]},"target_video_url":{"type":["string","null"]},"target_comment_url":{"type":["string","null"]}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false},"created_count":{"type":"integer","minimum":0,"maximum":200},"rejected_count":{"type":"integer","minimum":0,"maximum":200},"credits_charged":{"type":"integer","minimum":0,"maximum":200,"description":"Exact committed charge. It equals accepted tasks at the current 1-credit rate; rejected rows never contribute."}},"additionalProperties":false},"CancelCommentTaskResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["id","status","credits_refunded"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["cancelled"]},"credits_refunded":{"type":"integer","minimum":1,"description":"Exact stored task cost refunded in the same transaction as cancellation. Current tasks return 1; historical tasks may return a different amount."}},"additionalProperties":false}},"additionalProperties":false},"CommentVerificationTimelineResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["task_id","status","attempts"],"properties":{"task_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","submitted","verified_auto","needs_review","rejected","finalized","cancelled","pending_corrections","manually_confirmed"]},"attempts":{"type":"array","items":{"type":"object","required":["attempt_n","scraped_at","outcome_kind","verified","match_score","found_comment_id","reason","comments_scraped","platform"],"properties":{"attempt_n":{"type":"integer","minimum":1},"scraped_at":{"type":"string","format":"date-time"},"outcome_kind":{"type":["string","null"]},"verified":{"type":"boolean"},"match_score":{"type":"number","minimum":0},"found_comment_id":{"type":["string","null"]},"reason":{"type":["string","null"]},"comments_scraped":{"type":["integer","null"],"minimum":0},"platform":{"type":["string","null"],"enum":["tiktok","instagram","youtube",null]}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false},"CreateCommentTaskRequest":{"description":"One task object or a partial-success batch of 1 to 200 tasks. Each accepted task costs 1 credit. Durable validation, the accepted-task debit, and all accepted inserts commit atomically; rejected rows are never debited.","oneOf":[{"type":"object","required":["saved_account_id","comment_text"],"properties":{"saved_account_id":{"type":"string","format":"uuid","description":"Client-owned saved account that will post the comment. TokPortal Coverage must currently allow tasks, unless the account is permanently grandfathered."},"target_type":{"type":"string","enum":["video","comment"],"description":"Target type. 'video' (default) posts a comment under a video; 'comment' replies to a specific comment (TikTok only)."},"target_video_url":{"type":"string","minLength":1,"description":"Required when target_type is 'video' (or omitted). Any public TikTok/Instagram video URL, including a third party's — that is the intended use. Its platform must match the posting account's platform (COMMENT_PLATFORM_MISMATCH otherwise)."},"target_comment_url":{"type":"string","minLength":1,"description":"Required when target_type is 'comment'. TikTok comment deep-link (Share comment → Copy link); short or full form."},"comment_text":{"type":"string","minLength":1,"maxLength":10000,"description":"Exact text to post. The effective limit is 150 characters for TikTok and 2,200 for Instagram. Deduplicate locally on (saved_account_id, target URL, comment_text): two calls carrying the same comment under different Idempotency-Keys create two tasks and bill twice."},"brief_id":{"type":["string","null"],"format":"uuid","description":"Optional comment brief owned by the same client."}},"additionalProperties":false},{"type":"object","required":["tasks"],"properties":{"tasks":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","required":["saved_account_id","comment_text"],"properties":{"saved_account_id":{"type":"string","format":"uuid","description":"Client-owned saved account that will post the comment. TokPortal Coverage must currently allow tasks, unless the account is permanently grandfathered."},"target_type":{"type":"string","enum":["video","comment"],"description":"Target type. 'video' (default) posts a comment under a video; 'comment' replies to a specific comment (TikTok only)."},"target_video_url":{"type":"string","minLength":1,"description":"Required when target_type is 'video' (or omitted). Any public TikTok/Instagram video URL, including a third party's — that is the intended use. Its platform must match the posting account's platform (COMMENT_PLATFORM_MISMATCH otherwise)."},"target_comment_url":{"type":"string","minLength":1,"description":"Required when target_type is 'comment'. TikTok comment deep-link (Share comment → Copy link); short or full form."},"comment_text":{"type":"string","minLength":1,"maxLength":10000,"description":"Exact text to post. The effective limit is 150 characters for TikTok and 2,200 for Instagram. Deduplicate locally on (saved_account_id, target URL, comment_text): two calls carrying the same comment under different Idempotency-Keys create two tasks and bill twice."},"brief_id":{"type":["string","null"],"format":"uuid","description":"Optional comment brief owned by the same client."}},"additionalProperties":false}}},"additionalProperties":false}]},"DisputeCommentRequest":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"additionalProperties":false},"CreateWebhookEndpointRequest":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","maxLength":2000},"events":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","enum":["webhook.test","bundle.created","bundle.published","bundle.cancelled","bundle.archived","account.configured","account.published","account.in_review","account.pending_corrections","account.finalized","account.remade","account.banned","account.ban_appeal.submitted","account.ban_appeal.resolved","account.ban_resolution.decided","video.configured","video.in_review","video.published","video.pending_corrections","video.finalized","warming.session_started","warming.term_verified","warming.session_completed","subscription.renewed","subscription.lapsed","subscription.cancelled","subscription.reactivated","subscription.ended","account.revealed","credits.restored"]},"description":"Call listWebhookEvents for the description, trigger condition and payload schema of every event. Note in particular: account.published fires when YOU publish the order, NOT when the account is delivered — the delivery signal is account.in_review, and account.finalized fires when the account review is approved. warming.session_started is not emitted for warming whose terms were set at bundle creation."},"description":{"type":"string","maxLength":500},"enabled":{"type":"boolean","default":true}},"additionalProperties":false},"UpdateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2000},"events":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","enum":["webhook.test","bundle.created","bundle.published","bundle.cancelled","bundle.archived","account.configured","account.published","account.in_review","account.pending_corrections","account.finalized","account.remade","account.banned","account.ban_appeal.submitted","account.ban_appeal.resolved","account.ban_resolution.decided","video.configured","video.in_review","video.published","video.pending_corrections","video.finalized","warming.session_started","warming.term_verified","warming.session_completed","subscription.renewed","subscription.lapsed","subscription.cancelled","subscription.reactivated","subscription.ended","account.revealed","credits.restored"]}},"description":{"type":["string","null"],"maxLength":500},"enabled":{"type":"boolean"}},"minProperties":1,"additionalProperties":false},"WebhookEventsResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["events","envelope","delivery","signature"],"properties":{"events":{"type":"array","items":{"type":"object","required":["type","category","availability","description","when","payload_schema","example_payload"],"properties":{"type":{"type":"string","enum":["webhook.test","bundle.created","bundle.published","bundle.cancelled","bundle.archived","account.configured","account.published","account.in_review","account.pending_corrections","account.finalized","account.remade","account.banned","account.ban_appeal.submitted","account.ban_appeal.resolved","account.ban_resolution.decided","video.configured","video.in_review","video.published","video.pending_corrections","video.finalized","warming.session_started","warming.term_verified","warming.session_completed","subscription.renewed","subscription.lapsed","subscription.cancelled","subscription.reactivated","subscription.ended","account.revealed","credits.restored"]},"category":{"type":"string","enum":["webhook","bundle","account","video","comment","warming"]},"availability":{"type":"string","enum":["emitted","subscribable"]},"description":{"type":"string"},"when":{"type":"string"},"payload_schema":{"type":"object","additionalProperties":true},"example_payload":{"type":"object","additionalProperties":true}}}},"envelope":{"type":"object","required":["id","type","api_version","created_at","data"],"properties":{"id":{"type":"string","pattern":"^evt_"},"type":{"type":"string","enum":["webhook.test","bundle.created","bundle.published","bundle.cancelled","bundle.archived","account.configured","account.published","account.in_review","account.pending_corrections","account.finalized","account.remade","account.banned","account.ban_appeal.submitted","account.ban_appeal.resolved","account.ban_resolution.decided","video.configured","video.in_review","video.published","video.pending_corrections","video.finalized","warming.session_started","warming.term_verified","warming.session_completed","subscription.renewed","subscription.lapsed","subscription.cancelled","subscription.reactivated","subscription.ended","account.revealed","credits.restored"]},"api_version":{"type":"string","example":"2026-05-25"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}}},"delivery":{"type":"object","required":["method","content_type","timeout_ms","user_agent","headers"],"properties":{"method":{"type":"string","enum":["POST"]},"content_type":{"type":"string","enum":["application/json"]},"timeout_ms":{"type":"integer","example":8000},"user_agent":{"type":"string","example":"TokPortal-Webhooks/1.0"},"headers":{"type":"array","items":{"type":"string"}}}},"signature":{"type":"object","required":["header","scheme","signed_payload","algorithm","default_tolerance_seconds"],"properties":{"header":{"type":"string","enum":["TokPortal-Signature"]},"scheme":{"type":"string","example":"t={unix_timestamp},v1={hmac_sha256}"},"signed_payload":{"type":"string","example":"{timestamp}.{raw_body}"},"algorithm":{"type":"string","enum":["HMAC-SHA256"]},"default_tolerance_seconds":{"type":"integer","example":300}}}},"example":{"events":[{"type":"webhook.test","category":"webhook","availability":"emitted","description":"A signed test event sent on demand to validate an endpoint.","when":"Sent when you call POST /webhooks/{id}/test.","payload_schema":{"type":"object","required":["webhook_endpoint_id","message"],"properties":{"webhook_endpoint_id":{"type":"string","format":"uuid"},"message":{"type":"string"}}},"example_payload":{"webhook_endpoint_id":"33333333-4444-4555-8666-777777777777","message":"TokPortal webhook test event"}},{"type":"bundle.created","category":"bundle","availability":"emitted","description":"A bundle was created through the public API.","when":"Emitted after a successful bundle creation.","payload_schema":{"type":"object","required":["bundle_id"],"properties":{"bundle_id":{"type":"string","format":"uuid"},"external_ref":{"type":["string","null"]},"status":{"type":"string"},"platform":{"type":"string"},"bundle_type":{"type":"string"}}},"example_payload":{"bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","external_ref":"partner-order-123","status":"pending_setup","platform":"tiktok","bundle_type":"account_and_videos"}},{"type":"bundle.published","category":"bundle","availability":"emitted","description":"A bundle was published.","when":"Emitted after a bundle publish request succeeds.","payload_schema":{"type":"object","required":["bundle_id"],"properties":{"bundle_id":{"type":"string","format":"uuid"},"external_ref":{"type":["string","null"]},"status":{"type":"string"},"platform":{"type":"string"},"bundle_type":{"type":"string"}}},"example_payload":{"bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","external_ref":"partner-order-123","status":"published","platform":"tiktok","bundle_type":"account_and_videos"}},{"type":"bundle.cancelled","category":"bundle","availability":"emitted","description":"A bundle was cancelled. No further videos will be posted on it.","when":"Emitted when a bundle is cancelled: the bundle's account was banned (validated ban report with account_banned=true, and an account.banned event fires alongside), a ban-check was accepted with the cancel and refund resolution, or staff cancelled the bundle manually. Publishing to a cancelled bundle returns 409 BUNDLE_INVALID_STATUS.","payload_schema":{"type":"object","required":["bundle_id","reason","cancelled_at"],"properties":{"bundle_id":{"type":"string","format":"uuid"},"external_ref":{"type":["string","null"]},"platform":{"type":"string"},"reason":{"type":"string"},"cancelled_at":{"type":"string","format":"date-time"},"account_banned":{"type":"boolean","description":"True when the cancellation was caused by the bundle's account being banned. An account.banned event fires alongside."},"saved_account_id":{"type":["string","null"],"format":"uuid"},"username":{"type":["string","null"]}}},"example_payload":{"bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","external_ref":"partner-order-123","platform":"tiktok","reason":"Account banned: Community guidelines violation","cancelled_at":"2026-07-06T19:13:43Z","account_banned":true,"saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","username":"launchprofile"}},{"type":"bundle.archived","category":"bundle","availability":"emitted","description":"An inactive bundle was archived from the manager workspace without changing TokPortal Coverage.","when":"Emitted after 60 days with no newly scheduled or posted video and no executable video task. New work can reopen the bundle.","payload_schema":{"type":"object","required":["bundle_id"],"properties":{"bundle_id":{"type":"string","format":"uuid"},"external_ref":{"type":["string","null"]},"status":{"type":"string"},"platform":{"type":"string"},"bundle_type":{"type":"string"}}},"example_payload":{"bundle_id":"11111111-2222-4333-8444-555555555555","external_ref":"campaign-august-01","status":"completed","archived_at":"2026-10-09T11:00:00Z","reason":"no_scheduled_or_posted_video_for_60_days","account_coverage_changed":false}},{"type":"account.configured","category":"account","availability":"emitted","description":"An account listing was configured.","when":"Emitted when PUT /bundles/{id}/account moves an account listing to configured.","payload_schema":{"type":"object","required":["account_id","bundle_id","status"],"properties":{"account_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":["string","null"],"format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"username":{"type":["string","null"]},"platform":{"type":"string"},"status":{"type":"string"},"previous_status":{"type":["string","null"]}}},"example_payload":{"account_id":"0d1e2f3a-4b5c-6789-8abc-def012345678","saved_account_id":null,"bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","username":"launchprofile","platform":"tiktok","status":"configured","previous_status":"pending"}},{"type":"account.in_review","category":"account","availability":"emitted","description":"An account listing entered customer review.","when":"Emitted whenever an account listing enters in_review, whatever moved it there — a manager submitting or resubmitting from the web or mobile app, a Bundle Social handoff, or an operator action. Delivered by a log drain rather than inline with the write, so expect up to a few minutes of lag.","payload_schema":{"type":"object","required":["account_id","bundle_id","status"],"properties":{"account_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":["string","null"],"format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"username":{"type":["string","null"]},"platform":{"type":"string"},"status":{"type":"string"},"previous_status":{"type":["string","null"]}}},"example_payload":{"account_id":"0d1e2f3a-4b5c-6789-8abc-def012345678","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","username":"launchprofile","platform":"tiktok","status":"in_review","previous_status":"accepted"}},{"type":"account.published","category":"account","availability":"emitted","description":"An account listing was published to an active bundle.","when":"Emitted when POST /bundles/{id}/publish moves a configured account listing to published.","payload_schema":{"type":"object","required":["account_id","bundle_id","status"],"properties":{"account_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":["string","null"],"format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"username":{"type":["string","null"]},"platform":{"type":"string"},"status":{"type":"string"},"previous_status":{"type":["string","null"]}}},"example_payload":{"account_id":"0d1e2f3a-4b5c-6789-8abc-def012345678","saved_account_id":null,"bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","username":"launchprofile","platform":"tiktok","status":"published","previous_status":"configured"}},{"type":"account.pending_corrections","category":"account","availability":"emitted","description":"Corrections were requested for an account listing.","when":"Emitted after POST /bundles/{id}/account/corrections moves an account listing from in_review to pending_corrections.","payload_schema":{"type":"object","required":["account_id","bundle_id","status"],"properties":{"account_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":["string","null"],"format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"username":{"type":["string","null"]},"platform":{"type":"string"},"status":{"type":"string"},"previous_status":{"type":["string","null"]}}},"example_payload":{"account_id":"0d1e2f3a-4b5c-6789-8abc-def012345678","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","username":"launchprofile","platform":"tiktok","status":"pending_corrections","previous_status":"in_review"}},{"type":"account.finalized","category":"account","availability":"emitted","description":"An account listing was approved and finalized.","when":"Emitted after POST /bundles/{id}/account/finalize succeeds.","payload_schema":{"type":"object","required":["account_id","bundle_id","status"],"properties":{"account_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":["string","null"],"format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"username":{"type":["string","null"]},"platform":{"type":"string"},"status":{"type":"string"},"previous_status":{"type":["string","null"]}}},"example_payload":{"account_id":"0d1e2f3a-4b5c-6789-8abc-def012345678","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","username":"launchprofile","platform":"tiktok","status":"finalized","previous_status":"in_review"}},{"type":"account.remade","category":"account","availability":"emitted","description":"An account was remade after the previous one was banned or lost.","when":"Emitted when a bundle/account is remade. The previous saved account is removed and the bundle is rebuilt in place under the SAME bundle_id (use it, or your external_ref, as the stable anchor). The rebuilt account is created later by the manager and surfaces through subsequent account.* events on the same bundle_id.","payload_schema":{"type":"object","required":["bundle_id","remade_count"],"properties":{"bundle_id":{"type":"string","format":"uuid"},"external_ref":{"type":["string","null"]},"platform":{"type":"string"},"old_username":{"type":["string","null"]},"new_username":{"type":["string","null"]},"old_account_id":{"type":["string","null"],"format":"uuid"},"reason":{"type":["string","null"]},"mode":{"type":"string"},"remade_count":{"type":"integer","minimum":1},"remade_at":{"type":["string","null"],"format":"date-time"}}},"example_payload":{"bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","external_ref":"partner-order-123","platform":"tiktok","old_username":"launchprofile","new_username":"launchprofile_","old_account_id":"0d1e2f3a-4b5c-6789-8abc-def012345678","reason":"account banned/not found","mode":"republish","remade_count":1,"remade_at":"2026-06-09T00:36:24Z"}},{"type":"account.banned","category":"account","availability":"emitted","description":"An account managed for one of your bundles was banned by the platform.","when":"Emitted when the manager reports a ban and no appeal was available, when the platform refused the ban appeal, or when staff resets a mission whose account still had an open ban report (the account is retired: account.remade and account.ban_resolution.decided with resolution 'remake' fire alongside, and other open bundles on that account are cancelled with bundle.cancelled). The saved account is marked banned (banned_at/banned_reason) but stays visible. Staff reviews every ban report. Automated ban scans never emit this event on their own.","payload_schema":{"type":"object","required":["bundle_id","appeal_status"],"properties":{"bundle_id":{"type":["string","null"],"format":"uuid"},"saved_account_id":{"type":["string","null"],"format":"uuid"},"username":{"type":["string","null"]},"platform":{"type":"string"},"reason":{"type":["string","null"]},"appeal_status":{"type":"string","enum":["appeal_refused","no_appeal_banned"]},"banned_at":{"type":"string","format":"date-time"}}},"example_payload":{"bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","username":"launchprofile","platform":"tiktok","reason":"Community guidelines violation notice shown in-app","appeal_status":"appeal_refused","banned_at":"2026-07-03T10:15:00Z"}},{"type":"account.ban_appeal.submitted","category":"account","availability":"emitted","description":"The manager filed a platform ban appeal for an account managed for one of your bundles.","when":"Emitted when the manager reports a ban AND files a platform appeal. The account is unavailable while the appeal is pending, but it is NOT yet marked banned (no account.banned event fires, bundles stay open). A later account.ban_appeal.resolved event carries the platform's decision.","payload_schema":{"type":"object","required":["appeal_id","appeal_status","submitted_at"],"properties":{"appeal_id":{"type":"string","format":"uuid"},"bundle_id":{"type":["string","null"],"format":"uuid"},"saved_account_id":{"type":["string","null"],"format":"uuid"},"username":{"type":["string","null"]},"platform":{"type":"string"},"appeal_status":{"type":"string","enum":["appeal_pending"]},"submitted_at":{"type":"string","format":"date-time"}}},"example_payload":{"appeal_id":"5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","username":"launchprofile","platform":"tiktok","appeal_status":"appeal_pending","submitted_at":"2026-07-01T08:30:00Z"}},{"type":"account.ban_appeal.resolved","category":"account","availability":"emitted","description":"A platform ban appeal filed by the manager reached a final decision.","when":"Emitted when the manager reports the platform's answer to a ban appeal: resolution 'appeal_accepted' (account survived, nothing else changes) or 'appeal_refused' (the account is banned, and an account.banned event fires alongside).","payload_schema":{"type":"object","required":["appeal_id","resolution"],"properties":{"appeal_id":{"type":"string","format":"uuid"},"bundle_id":{"type":["string","null"],"format":"uuid"},"saved_account_id":{"type":["string","null"],"format":"uuid"},"username":{"type":["string","null"]},"platform":{"type":"string"},"resolution":{"type":"string","enum":["appeal_accepted","appeal_refused"]},"reason":{"type":["string","null"]},"decided_at":{"type":"string","format":"date-time"}}},"example_payload":{"appeal_id":"5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","username":"launchprofile","platform":"tiktok","resolution":"appeal_refused","reason":"Community guidelines violation notice shown in-app","decided_at":"2026-07-03T10:15:00Z"}},{"type":"account.ban_resolution.decided","category":"account","availability":"emitted","description":"Staff decided the commercial outcome of a confirmed ban: refund, remake, or no_remake.","when":"Emitted when staff resolves a confirmed ban report (status appeal_refused or no_appeal_banned) from the Ban Appeals queue: 'refund' restores credits (refund_credits carries the amount and a credits.restored event can fire alongside), 'remake' resets and relists the mission under the same bundle_id (an account.remade event fires alongside), and 'no_remake' closes the case without compensation (reason_code 'tos_ban' means the account was banned for a direct Terms of Service violation). A staff reset of a mission with an open ban report also emits it with resolution 'remake', after account.banned and account.remade.","payload_schema":{"type":"object","required":["appeal_id","resolution","resolved_at"],"properties":{"appeal_id":{"type":"string","format":"uuid"},"bundle_id":{"type":["string","null"],"format":"uuid"},"saved_account_id":{"type":["string","null"],"format":"uuid"},"username":{"type":["string","null"]},"platform":{"type":"string"},"resolution":{"type":"string","enum":["refund","remake","no_remake"],"description":"Commercial outcome decided by staff: refund (credits restored), remake (the mission is reset and relisted — an account.remade event fires alongside), or no_remake (no compensation; see reason_code)."},"reason_code":{"type":["string","null"],"description":"Machine-readable resolution reason, e.g. eligible_refund, eligible_credit_restoration, replacement_approved, tos_ban, tos_violation, content_related, custom."},"refund_credits":{"type":"integer","minimum":0},"resolved_at":{"type":"string","format":"date-time"}}},"example_payload":{"appeal_id":"5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","username":"launchprofile","platform":"tiktok","resolution":"refund","reason_code":"eligible_refund","refund_credits":42,"resolved_at":"2026-07-04T16:45:00Z"}},{"type":"video.configured","category":"video","availability":"emitted","description":"A video listing was configured or unscheduled back to configured.","when":"Emitted when a video configuration, CSV import, batch configuration, or unschedule action moves a video listing to configured.","payload_schema":{"type":"object","required":["video_id","bundle_id","position","status"],"properties":{"video_id":{"type":"string","format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":1},"status":{"type":"string"},"previous_status":{"type":["string","null"]},"platform_url":{"type":["string","null"],"format":"uri"}}},"example_payload":{"video_id":"11111111-2222-4333-8444-555555555555","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","position":1,"status":"configured","previous_status":"pending","platform_url":null}},{"type":"video.in_review","category":"video","availability":"emitted","description":"A video listing entered customer review.","when":"Emitted when a manager submits a posted video URL and the video listing moves to in_review.","payload_schema":{"type":"object","required":["video_id","bundle_id","position","status"],"properties":{"video_id":{"type":"string","format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":1},"status":{"type":"string"},"previous_status":{"type":["string","null"]},"platform_url":{"type":["string","null"],"format":"uri"}}},"example_payload":{"video_id":"11111111-2222-4333-8444-555555555555","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","position":1,"status":"in_review","previous_status":"configured","platform_url":null}},{"type":"video.published","category":"video","availability":"emitted","description":"A video was published to its destination platform.","when":"Emitted after POST /bundles/{id}/videos/{position}/publish succeeds.","payload_schema":{"type":"object","required":["video_id","bundle_id","position","status"],"properties":{"video_id":{"type":"string","format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":1},"status":{"type":"string"},"previous_status":{"type":["string","null"]},"platform_url":{"type":["string","null"],"format":"uri"}}},"example_payload":{"video_id":"11111111-2222-4333-8444-555555555555","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","position":1,"status":"published","previous_status":"in_review","platform_url":"https://www.tiktok.com/@launchprofile/video/123"}},{"type":"video.pending_corrections","category":"video","availability":"emitted","description":"Corrections were requested for a video listing.","when":"Emitted after POST /bundles/{id}/videos/{position}/corrections moves a video listing from in_review to pending_corrections.","payload_schema":{"type":"object","required":["video_id","bundle_id","position","status"],"properties":{"video_id":{"type":"string","format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":1},"status":{"type":"string"},"previous_status":{"type":["string","null"]},"platform_url":{"type":["string","null"],"format":"uri"}}},"example_payload":{"video_id":"11111111-2222-4333-8444-555555555555","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","position":1,"status":"pending_corrections","previous_status":"in_review","platform_url":"https://www.tiktok.com/@launchprofile/video/123"}},{"type":"video.finalized","category":"video","availability":"emitted","description":"A video passed final review.","when":"Emitted after POST /bundles/{id}/videos/{position}/finalize succeeds.","payload_schema":{"type":"object","required":["video_id","bundle_id","position","status"],"properties":{"video_id":{"type":"string","format":"uuid"},"bundle_id":{"type":"string","format":"uuid"},"position":{"type":"integer","minimum":1},"status":{"type":"string"},"previous_status":{"type":["string","null"]},"platform_url":{"type":["string","null"],"format":"uri"}}},"example_payload":{"video_id":"11111111-2222-4333-8444-555555555555","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","position":1,"status":"finalized","previous_status":"in_review","platform_url":"https://www.tiktok.com/@launchprofile/video/123"}},{"type":"warming.session_started","category":"warming","availability":"emitted","description":"An advanced warming session started on one of your accounts.","when":"Emitted when POST /accounts/{id}/rewarm creates a session (it starts immediately), and when configuring the niche targets of a count-only purchase (PUT /bundles/{id}/account with advanced_warming_terms) starts the session because the account/order is already active. Bundle-sourced sessions whose targets were set at creation start via an internal transition when the manager begins working on the account and do NOT emit this event. Track them through GET /warming-sessions/{id} or GET /accounts/{id}/warming-sessions instead.","payload_schema":{"type":"object","required":["session_id","terms_total"],"properties":{"session_id":{"type":"string","format":"uuid"},"account_id":{"type":["string","null"],"format":"uuid","description":"Saved account the session warms."},"bundle_id":{"type":["string","null"],"format":"uuid"},"order_id":{"type":["string","null"],"format":"uuid"},"source":{"type":"string","enum":["bundle","rewarm"]},"platform":{"type":"string","enum":["tiktok","instagram"]},"terms_total":{"type":"integer","minimum":3,"maximum":30},"search_terms":{"type":"array","items":{"type":"string"}},"credits_cost":{"type":"integer"},"started_at":{"type":["string","null"],"format":"date-time"}}},"example_payload":{"session_id":"6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d","account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","bundle_id":"9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c","order_id":"2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e","source":"rewarm","platform":"tiktok","terms_total":6,"search_terms":["healthy meal prep","high protein recipes","meal prep containers","quick healthy dinner","macro friendly meals","budget meal prep"],"credits_cost":18,"started_at":"2026-07-10T12:00:00Z"}},{"type":"warming.term_verified","category":"warming","availability":"emitted","description":"One advanced-warming search term was completed and its screen recording passed verification.","when":"Emitted after the manager's recording for a term is verified. The payload includes the client-facing per-term report (videos watched, likes, saves, comment, sample content, proof video link).","payload_schema":{"type":"object","required":["session_id","task_id","term","report"],"properties":{"session_id":{"type":"string","format":"uuid"},"task_id":{"type":"string","format":"uuid"},"term":{"type":"string"},"report":{"type":"object","description":"Client-facing per-term warming report, built after the term's screen recording is verified.","required":["term","day_index","verified_at"],"properties":{"term":{"type":"string"},"day_index":{"type":"integer","minimum":1,"maximum":3},"verified_at":{"type":"string","format":"date-time"},"videos_watched":{"type":"integer"},"likes":{"type":"integer"},"saves":{"type":"integer"},"comments":{"type":"integer"},"keywords_seen":{"type":"array","items":{"type":"string"}},"sample_videos":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"creator":{"type":"string"}}}},"proof_video_url":{"type":["string","null"],"format":"uri"},"summary":{"type":"string"}}}}},"example_payload":{"session_id":"6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d","task_id":"0f1e2d3c-4b5a-4697-8877-665544332211","term":"healthy meal prep","report":{"term":"healthy meal prep","day_index":1,"verified_at":"2026-07-10T14:05:00Z","videos_watched":15,"likes":5,"saves":5,"comments":1,"keywords_seen":["meal prep","high protein","recipes"],"sample_videos":[{"description":"5 high-protein lunches for the week","creator":"@prepqueen"}],"proof_video_url":"https://media.tokportal.com/warming/session/task/recording.mp4","summary":"Searched \"healthy meal prep\" and engaged with the top results. Watched the videos through, liked and saved several, and left a comment."}}},{"type":"warming.session_completed","category":"warming","availability":"emitted","description":"An advanced warming session finished and every search term was verified.","when":"Emitted when the last term of a session is verified. The payload includes the aggregated session report with per-term details and engagement totals.","payload_schema":{"type":"object","required":["session_id","report"],"properties":{"session_id":{"type":"string","format":"uuid"},"report":{"type":"object","description":"Aggregated client-facing report for the whole warming session, built when the session completes.","required":["terms_total","terms_verified","totals"],"properties":{"terms_total":{"type":"integer"},"terms_verified":{"type":"integer"},"terms_expired":{"type":"integer"},"totals":{"type":"object","properties":{"videos_watched":{"type":"integer"},"likes":{"type":"integer"},"saves":{"type":"integer"},"comments":{"type":"integer"}}},"terms":{"type":"array","items":{"type":"object","description":"Client-facing per-term warming report, built after the term's screen recording is verified.","required":["term","day_index","verified_at"],"properties":{"term":{"type":"string"},"day_index":{"type":"integer","minimum":1,"maximum":3},"verified_at":{"type":"string","format":"date-time"},"videos_watched":{"type":"integer"},"likes":{"type":"integer"},"saves":{"type":"integer"},"comments":{"type":"integer"},"keywords_seen":{"type":"array","items":{"type":"string"}},"sample_videos":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"creator":{"type":"string"}}}},"proof_video_url":{"type":["string","null"],"format":"uri"},"summary":{"type":"string"}}}},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"summary":{"type":"string"}}}}},"example_payload":{"session_id":"6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d","report":{"terms_total":6,"terms_verified":6,"terms_expired":0,"totals":{"videos_watched":91,"likes":31,"saves":30,"comments":6},"terms":[{"term":"healthy meal prep","day_index":1,"verified_at":"2026-07-10T14:05:00Z","videos_watched":15,"likes":5,"saves":5,"comments":1,"keywords_seen":["meal prep","high protein","recipes"],"sample_videos":[{"description":"5 high-protein lunches for the week","creator":"@prepqueen"}],"proof_video_url":"https://media.tokportal.com/warming/session/task/recording.mp4","summary":"Searched \"healthy meal prep\" and engaged with the top results. Watched the videos through, liked and saved several, and left a comment."}],"started_at":"2026-07-10T12:00:00Z","completed_at":"2026-07-13T09:30:00Z","summary":"Warmed the account over 3 days across 6 search terms: 91 videos watched, 31 likes, 30 saves, and 6 comments posted."}}},{"type":"subscription.renewed","category":"subscription","availability":"emitted","description":"TokPortal Coverage renewed for another 30-day period.","when":"Emitted after the automatic 25-credit renewal debit succeeds.","payload_schema":{"type":"object","required":["subscription_id","saved_account_id"],"properties":{"product":{"type":["string","null"],"enum":["tokportal_coverage",null]},"subscription_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":"string","format":"uuid"},"previous_status":{"type":["string","null"]},"period_start":{"type":["string","null"],"format":"date-time"},"period_end":{"type":["string","null"],"format":"date-time"},"current_period_start":{"type":["string","null"],"format":"date-time"},"current_period_end":{"type":["string","null"],"format":"date-time"},"credits_charged":{"type":"integer","minimum":0},"unpaid_periods_paid":{"type":"integer","minimum":0},"reactivation_was_free":{"type":"boolean"},"period_rate_credits":{"type":"integer","minimum":0},"lapsed_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"reactivation_requires_current_period":{"type":"boolean","deprecated":true,"description":"Deprecated compatibility field. Always false."},"reactivation_may_be_free_until":{"type":["string","null"],"format":"date-time"},"resumed_tasks":{"type":["object","null"]},"reason":{"type":["string","null"]},"credit_transaction_id":{"type":["string","null"],"format":"uuid"}}},"example_payload":{"subscription_id":"11111111-2222-4333-8444-555555555555","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","period_start":"2026-09-10T11:00:00Z","period_end":"2026-10-10T11:00:00Z","credits_charged":25,"credit_transaction_id":"22222222-3333-4444-8555-666666666666"}},{"type":"subscription.lapsed","category":"subscription","availability":"emitted","description":"TokPortal Coverage paused because its automatic renewal could not be paid.","when":"Emitted when the automatic renewal finds an insufficient credit balance.","payload_schema":{"type":"object","required":["subscription_id","saved_account_id"],"properties":{"product":{"type":["string","null"],"enum":["tokportal_coverage",null]},"subscription_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":"string","format":"uuid"},"previous_status":{"type":["string","null"]},"period_start":{"type":["string","null"],"format":"date-time"},"period_end":{"type":["string","null"],"format":"date-time"},"current_period_start":{"type":["string","null"],"format":"date-time"},"current_period_end":{"type":["string","null"],"format":"date-time"},"credits_charged":{"type":"integer","minimum":0},"unpaid_periods_paid":{"type":"integer","minimum":0},"reactivation_was_free":{"type":"boolean"},"period_rate_credits":{"type":"integer","minimum":0},"lapsed_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"reactivation_requires_current_period":{"type":"boolean","deprecated":true,"description":"Deprecated compatibility field. Always false."},"reactivation_may_be_free_until":{"type":["string","null"],"format":"date-time"},"resumed_tasks":{"type":["object","null"]},"reason":{"type":["string","null"]},"credit_transaction_id":{"type":["string","null"],"format":"uuid"}}},"example_payload":{"subscription_id":"11111111-2222-4333-8444-555555555555","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","period_start":"2026-09-10T11:00:00Z","period_end":"2026-10-10T11:00:00Z","lapsed_at":"2026-09-10T11:00:02Z","reason":"insufficient_credits"}},{"type":"subscription.cancelled","category":"subscription","availability":"emitted","description":"TokPortal Coverage was paused manually for an account.","when":"Committed atomically when the client pauses coverage, then delivered asynchronously with retries. Current tasks are withheld and new tasks are blocked until reactivation; the fresh quote may be free while a paid or included period remains.","payload_schema":{"type":"object","required":["subscription_id","saved_account_id"],"properties":{"product":{"type":["string","null"],"enum":["tokportal_coverage",null]},"subscription_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":"string","format":"uuid"},"previous_status":{"type":["string","null"]},"period_start":{"type":["string","null"],"format":"date-time"},"period_end":{"type":["string","null"],"format":"date-time"},"current_period_start":{"type":["string","null"],"format":"date-time"},"current_period_end":{"type":["string","null"],"format":"date-time"},"credits_charged":{"type":"integer","minimum":0},"unpaid_periods_paid":{"type":"integer","minimum":0},"reactivation_was_free":{"type":"boolean"},"period_rate_credits":{"type":"integer","minimum":0},"lapsed_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"reactivation_requires_current_period":{"type":"boolean","deprecated":true,"description":"Deprecated compatibility field. Always false."},"reactivation_may_be_free_until":{"type":["string","null"],"format":"date-time"},"resumed_tasks":{"type":["object","null"]},"reason":{"type":["string","null"]},"credit_transaction_id":{"type":["string","null"],"format":"uuid"}}},"example_payload":{"subscription_id":"11111111-2222-4333-8444-555555555555","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","cancelled_at":"2026-09-18T11:00:00Z","current_period_end":"2026-10-10T11:00:00Z","reactivation_requires_current_period":false,"reactivation_may_be_free_until":"2026-10-10T11:00:00Z","reason":"cancelled_by_client"}},{"type":"subscription.reactivated","category":"subscription","availability":"emitted","description":"Paused TokPortal Coverage was reactivated atomically.","when":"Committed atomically when the quote snapshot is confirmed and Coverage resumes, then delivered asynchronously with retries. credits_charged is zero and credit_transaction_id is null when the current billing period was already paid or included.","payload_schema":{"type":"object","required":["subscription_id","saved_account_id"],"properties":{"product":{"type":["string","null"],"enum":["tokportal_coverage",null]},"subscription_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":"string","format":"uuid"},"previous_status":{"type":["string","null"]},"period_start":{"type":["string","null"],"format":"date-time"},"period_end":{"type":["string","null"],"format":"date-time"},"current_period_start":{"type":["string","null"],"format":"date-time"},"current_period_end":{"type":["string","null"],"format":"date-time"},"credits_charged":{"type":"integer","minimum":0},"unpaid_periods_paid":{"type":"integer","minimum":0},"reactivation_was_free":{"type":"boolean"},"period_rate_credits":{"type":"integer","minimum":0},"lapsed_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"reactivation_requires_current_period":{"type":"boolean","deprecated":true,"description":"Deprecated compatibility field. Always false."},"reactivation_may_be_free_until":{"type":["string","null"],"format":"date-time"},"resumed_tasks":{"type":["object","null"]},"reason":{"type":["string","null"]},"credit_transaction_id":{"type":["string","null"],"format":"uuid"}}},"example_payload":{"subscription_id":"11111111-2222-4333-8444-555555555555","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","credits_charged":50,"unpaid_periods_paid":2,"reactivation_was_free":false,"period_rate_credits":25,"current_period_start":"2026-10-10T11:00:00Z","current_period_end":"2026-11-09T11:00:00Z","credit_transaction_id":"22222222-3333-4444-8555-666666666666"}},{"type":"subscription.ended","category":"subscription","availability":"emitted","description":"TokPortal Coverage ended permanently after a confirmed banned-account refund or credit-restoration resolution.","when":"Emitted after staff completes the eligible refund or credit-restoration resolution for a confirmed banned account. No future renewal or reactivation is possible.","payload_schema":{"type":"object","required":["product","subscription_id","saved_account_id","status","ended_at","ended_reason","credits_restored","unpaid_periods_voided"],"properties":{"product":{"type":"string","enum":["tokportal_coverage"]},"subscription_id":{"type":"string","format":"uuid"},"saved_account_id":{"type":"string","format":"uuid"},"previous_status":{"type":["string","null"]},"status":{"type":"string","enum":["ended_ban"]},"ended_at":{"type":"string","format":"date-time"},"ended_reason":{"type":["string","null"]},"appeal_id":{"type":["string","null"],"format":"uuid"},"credits_restored":{"type":"integer","minimum":0},"unpaid_periods_voided":{"type":"integer","minimum":0}}},"example_payload":{"product":"tokportal_coverage","subscription_id":"11111111-2222-4333-8444-555555555555","saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","previous_status":"active","status":"ended_ban","ended_at":"2026-09-18T11:00:00Z","ended_reason":"eligible_platform_ban_refunded","appeal_id":"33333333-4444-4555-8666-777777777777","credits_restored":57,"unpaid_periods_voided":0}},{"type":"account.revealed","category":"account","availability":"emitted","description":"The first credential or verification-code reveal was recorded for the account.","when":"Emitted once after the first successful reveal. Under the managed reveal policy, TokPortal Coverage ends permanently; a prior-policy reveal reports management_ended as false.","payload_schema":{"type":"object","required":["saved_account_id","revealed_at","credits_charged","management_ended"],"properties":{"saved_account_id":{"type":"string","format":"uuid"},"revealed_at":{"type":"string","format":"date-time"},"credits_charged":{"type":"integer","minimum":0},"management_ended":{"type":"boolean"}}},"example_payload":{"saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","revealed_at":"2026-08-14T11:05:00Z","credits_charged":150,"management_ended":true}},{"type":"credits.restored","category":"credits","availability":"emitted","description":"Credits were restored after an eligible managed-account ban.","when":"Emitted after the staff ban resolution restores eligible credits with a 60-day expiry.","payload_schema":{"type":"object","required":["saved_account_id","credits_restored","expires_at"],"properties":{"saved_account_id":{"type":"string","format":"uuid"},"appeal_id":{"type":["string","null"],"format":"uuid"},"credits_restored":{"type":"integer","minimum":1},"expires_at":{"type":"string","format":"date-time"},"credit_transaction_id":{"type":["string","null"],"format":"uuid"}}},"example_payload":{"saved_account_id":"7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60","appeal_id":"5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d","credits_restored":42,"expires_at":"2026-10-13T10:00:00Z","credit_transaction_id":"22222222-3333-4444-8555-666666666666"}}],"envelope":{"id":"evt_0123456789abcdef0123456789abcdef","type":"bundle.published","api_version":"2026-05-25","created_at":"2026-06-01T12:00:00.000Z","data":{}},"delivery":{"method":"POST","content_type":"application/json","timeout_ms":8000,"user_agent":"TokPortal-Webhooks/1.0","headers":["TokPortal-Event-Id","TokPortal-Event-Type","TokPortal-Signature"]},"signature":{"header":"TokPortal-Signature","scheme":"t={unix_timestamp},v1={hmac_sha256}","signed_payload":"{timestamp}.{raw_body}","algorithm":"HMAC-SHA256","default_tolerance_seconds":300}}}}},"UploadVideoRequest":{"type":"object","required":["filename","bundle_id"],"properties":{"filename":{"type":"string","minLength":1,"maxLength":200},"content_type":{"type":"string","default":"video/mp4"},"bundle_id":{"type":"string","format":"uuid"}},"additionalProperties":false},"UploadImageRequest":{"type":"object","required":["filename","content_type","bundle_id"],"properties":{"filename":{"type":"string","minLength":1,"maxLength":200,"example":"profile.png","description":"Original file name. Used only as a fallback for the stored object's extension when content_type is not a recognised image type; content_type is what normally names the object. The response's storage_path is the authoritative key."},"content_type":{"type":"string","pattern":"^image/(jpeg|jpg|png|webp|gif)$","example":"image/png","description":"Allowed image MIME types: image/jpeg, image/jpg, image/png, image/webp, image/gif. This value determines the stored object's extension (image/png stores a .png); filename is only the fallback when the type is unrecognised. Send the type that matches the bytes you are about to PUT, and use it as the Content-Type of that PUT. Read storage_path on the response for the key the object actually landed under."},"bundle_id":{"type":"string","format":"uuid"},"purpose":{"type":"string","enum":["carousel","profile_picture"],"default":"carousel","description":"Which bucket the image is stored in. Use the response's storage_path (not public_url) for carousel_images and profile_picture_url."}},"additionalProperties":false},"UploadImageFromUrlRequest":{"type":"object","required":["url","bundle_id"],"properties":{"url":{"type":"string","format":"uri","description":"Public direct image URL."},"bundle_id":{"type":"string","format":"uuid"},"purpose":{"type":"string","enum":["carousel","profile_picture"],"default":"carousel"}},"additionalProperties":false},"CreateAnalyticsReportRequest":{"type":"object","properties":{"title":{"type":["string","null"],"maxLength":120,"description":"Report title. 120 characters, the real stored limit."},"template":{"type":["string","null"],"enum":["executive","agency","creator","minimal","growth","board",null],"description":"Report layout. Any other value is rejected with INVALID_FIELD rather than silently becoming executive. The applied template is echoed as applied.template on the JSON response and as X-TokPortal-Report-Template on the HTML export."},"brandName":{"type":["string","null"],"maxLength":80,"description":"White-label brand name (80 characters, the real stored limit). Applied only on the full analytics tier with a Farmer plan; on every other plan it is reset to TokPortal, and the response says so through applied.brand_name and canBrand — check them before promising a client a white-labelled document."},"brandAccent":{"type":["string","null"],"maxLength":40,"description":"White-label accent colour, #rrggbb (a #rgb short form is expanded). Named colours, rgb() and 8-digit hex are rejected with INVALID_FIELD instead of silently becoming the TokPortal default. Like brandName it only applies on a Farmer plan at the full tier; read applied.brand_accent back."},"accountIds":{"type":"array","items":{"type":"string","format":"uuid"}},"workspaceId":{"type":["string","null"],"format":"uuid"},"platforms":{"type":"array","items":{"type":"string","enum":["tiktok","instagram"]}},"countries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":5}},"query":{"type":["string","null"],"maxLength":120,"description":"Free-text filter. 120 characters, the real stored limit."},"from":{"type":["string","null"],"format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive start date, YYYY-MM-DD. A full ISO timestamp is accepted and truncated to its date; anything else is rejected with INVALID_FIELD rather than silently treated as no filter (which used to widen the report to the account's entire history). Must not be after `to`. The window actually applied comes back as applied.filters.from."},"to":{"type":["string","null"],"format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Inclusive end date, YYYY-MM-DD, same parsing as `from`. Echoed as applied.filters.to."}},"additionalProperties":false},"AiUsdAmount":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"AiAvailability":{"type":"object","properties":{"status":{"type":"string","enum":["available","blocked"]},"reason":{"type":"string"}},"required":["status"],"additionalProperties":false},"AiStatus":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the AI API/tools are available, including inspection during a generation pause."},"generation_enabled":{"type":"boolean"},"availability":{"$ref":"#/components/schemas/AiAvailability"},"generation_availability":{"$ref":"#/components/schemas/AiAvailability"}},"required":["enabled","availability"],"additionalProperties":false},"AiModel":{"type":"object","properties":{"id":{"type":"string"},"alias":{"type":"string"},"name":{"type":"string"},"modality":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"operations":{"type":"array","items":{"type":"string"}},"inputs":{"type":"array","items":{"type":"string"}},"outputs":{"type":"array","items":{"type":"string"}},"durations":{"type":"string"},"resolutions":{"type":"string"},"aspect_ratios":{"type":"string"},"schema_version":{"type":"string"},"schema":{"type":"object","additionalProperties":true,"description":"Current JSON Schema for this model's operations. Read on demand; not duplicated into every MCP tool."},"availability":{"$ref":"#/components/schemas/AiAvailability"}},"required":["id","alias","capabilities","availability"],"additionalProperties":false},"AiQuoteRequest":{"type":"object","properties":{"model":{"type":"string","minLength":1,"description":"Public model alias from GET /ai/models. Fetch its current schema first."},"operation":{"type":"string","minLength":1,"description":"Model operation/capability from its schema, including image, video, audio, chat, analysis, or verification where available."},"prompt":{"type":"string"},"assets":{"type":"object","additionalProperties":true},"controls":{"type":"object","additionalProperties":true},"options":{"type":"object","additionalProperties":true,"description":"Documented advanced options for the selected capability. No arbitrary provider URL, credentials, or HTTP route is accepted."}},"required":["model"],"additionalProperties":false},"AiQuote":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"request_hash":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"cost":{"type":"object","properties":{"currency":{"const":"USD"},"amount_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"max_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"pricing_version":{"type":"string"},"settlement":{"type":"string","enum":["fixed","verified_usage"]},"notice":{"type":"string"}},"required":["currency","amount_usd","max_usd","pricing_version"],"additionalProperties":false},"availability":{"$ref":"#/components/schemas/AiAvailability"}},"required":["id","request_hash","expires_at","cost","availability"],"additionalProperties":false},"AiGenerationRequest":{"type":"object","properties":{"model":{"type":"string","minLength":1,"description":"Public model alias from GET /ai/models. Fetch its current schema first."},"operation":{"type":"string","minLength":1,"description":"Model operation/capability from its schema, including image, video, audio, chat, analysis, or verification where available."},"prompt":{"type":"string"},"assets":{"type":"object","additionalProperties":true},"controls":{"type":"object","additionalProperties":true},"options":{"type":"object","additionalProperties":true,"description":"Documented advanced options for the selected capability. No arbitrary provider URL, credentials, or HTTP route is accepted."},"quote_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"max_cost_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."}},"required":[],"additionalProperties":false,"oneOf":[{"required":["model"],"not":{"required":["quote_id"]}},{"required":["quote_id","max_cost_usd"],"not":{"anyOf":[{"required":["model"]},{"required":["operation"]},{"required":["prompt"]},{"required":["assets"]},{"required":["controls"]},{"required":["options"]}]}}]},"AiJob":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"model":{"type":"string"},"operation":{"type":"string"},"status":{"type":"string","enum":["queued","submitting","submission_unknown","running","ingesting","succeeded","failed","cancelled","reconciliation_required"]},"financial_status":{"type":"string","enum":["reserved","settled","released","reconciliation_required"]},"price_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"max_price_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"charged_usd":{"anyOf":[{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},{"type":"null"}]},"quote_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"outputs":{"type":"object","additionalProperties":true,"description":"Normalized media/text output with TokPortal asset IDs where applicable."},"error":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"cancellation_requested":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","status"],"additionalProperties":false},"AiAsset":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"name":{"type":"string"},"kind":{"type":"string","enum":["image","video","audio","file"]},"status":{"type":"string"},"asset_ref":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer"},"url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}},"required":["id"],"additionalProperties":false},"AiReference":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"reference_ref":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"collection_id":{"anyOf":[{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},{"type":"null"}]},"asset_id":{"anyOf":[{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","status","reference_ref"],"additionalProperties":false},"AiCollection":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/AiReference"}},"next_asset_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name"],"additionalProperties":false},"AiVerification":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"verification_url":{"type":"string","format":"uri","description":"Explicitly authorized external human-verification flow. The verification token is never returned separately."},"external_verification":{"type":"boolean"},"collection_id":{"anyOf":[{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","status"],"additionalProperties":false},"AiLibrary":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"reference_ref":{"type":"string"},"title":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"metadata":{"type":"object","additionalProperties":true},"thumbnail_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["id","reference_ref"],"additionalProperties":false}},"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total_count":{"anyOf":[{"type":"integer"},{"type":"null"}]},"has_more":{"type":"boolean"}},"required":["items","page_number","page_size","total_count","has_more"],"additionalProperties":false},"AiVerificationRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string","maxLength":300},"consent":{"const":true}},"required":["name","consent"],"additionalProperties":false},"AiWallet":{"type":"object","properties":{"currency":{"const":"USD"},"balance_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"reserved_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"available_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"financial_hold":{"type":"boolean"},"financial_hold_reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["currency","balance_usd","reserved_usd","available_usd","financial_hold","financial_hold_reason"],"additionalProperties":false},"AiAssetImportRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string"},"collection_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},"required":["url"],"additionalProperties":false},"AiUploadRequest":{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer","minimum":1}},"required":["filename","content_type","size_bytes"],"additionalProperties":false},"AiUploadCompleteRequest":{"type":"object","properties":{"upload_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},"required":["upload_id"],"additionalProperties":false},"AiAssetUpdateRequest":{"type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}},"required":[],"additionalProperties":false},"AiCollectionRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string","maxLength":300}},"required":["name"],"additionalProperties":false},"AiManageRequest":{"type":"object","properties":{"action":{"type":"string","enum":["cancel_job","import_asset","create_upload","complete_upload","update_asset","delete_asset","create_collection","update_collection","delete_collection","add_collection_asset","remove_collection_asset","update_collection_asset","refresh_collection_asset","create_verification","refresh_verification"]},"id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"data":{"type":"object","additionalProperties":true}},"required":["action"],"additionalProperties":false,"oneOf":[{"properties":{"action":{"const":"cancel_job"}},"required":["id"]},{"properties":{"action":{"const":"import_asset"},"data":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string"},"collection_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},"required":["url"],"additionalProperties":false}},"required":["data"]},{"properties":{"action":{"const":"create_upload"},"data":{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer","minimum":1}},"required":["filename","content_type","size_bytes"],"additionalProperties":false}},"required":["data"]},{"properties":{"action":{"const":"complete_upload"},"data":{"type":"object","properties":{"upload_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},"required":["upload_id"],"additionalProperties":false}},"required":["data"]},{"properties":{"action":{"const":"update_asset"},"data":{"type":"object","properties":{"name":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}},"required":[],"additionalProperties":false}},"required":["id","data"]},{"properties":{"action":{"const":"delete_asset"}},"required":["id"]},{"properties":{"action":{"const":"create_collection"},"data":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string","maxLength":300}},"required":["name"],"additionalProperties":false}},"required":["data"]},{"properties":{"action":{"const":"update_collection"},"data":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string","maxLength":300}},"required":["name"],"additionalProperties":false}},"required":["id","data"]},{"properties":{"action":{"const":"delete_collection"}},"required":["id"]},{"properties":{"action":{"const":"add_collection_asset"},"data":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},"required":["asset_id"],"additionalProperties":false}},"required":["id","data"]},{"properties":{"action":{"const":"remove_collection_asset"},"data":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},"required":["asset_id"],"additionalProperties":false}},"required":["id","data"]},{"properties":{"action":{"const":"update_collection_asset"},"data":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"name":{"type":"string","minLength":1,"maxLength":64}},"required":["asset_id","name"],"additionalProperties":false}},"required":["id","data"]},{"properties":{"action":{"const":"refresh_collection_asset"},"data":{"type":"object","properties":{"asset_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."}},"required":["asset_id"],"additionalProperties":false}},"required":["id","data"]},{"properties":{"action":{"const":"create_verification"},"data":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string","maxLength":300},"consent":{"const":true}},"required":["name","consent"],"additionalProperties":false}},"required":["data"]},{"properties":{"action":{"const":"refresh_verification"}},"required":["id"]}]},"AiInspectResult":{"type":"object","additionalProperties":true,"description":"The same data as the selected canonical read endpoint; resource selects a fixed, authorization-checked operation."},"AiAccessRequest":{"type":"object","properties":{"enabled":{"type":"boolean"},"max_job_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"monthly_limit_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"consent":{"const":true},"consent_version":{"const":"ai-spend-v1"}},"required":["enabled"],"additionalProperties":false,"oneOf":[{"properties":{"enabled":{"const":false}}},{"properties":{"enabled":{"const":true}},"required":["max_job_usd","monthly_limit_usd","consent","consent_version"]}]},"AiAutoTopupRequest":{"type":"object","properties":{"enabled":{"type":"boolean"},"threshold_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"amount_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"monthly_limit_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"billing_consent":{"const":true},"consent_version":{"const":"ai-auto-topup-v1"}},"required":["enabled"],"additionalProperties":false,"oneOf":[{"properties":{"enabled":{"const":false}}},{"properties":{"enabled":{"const":true}},"required":["threshold_usd","amount_usd","monthly_limit_usd","billing_consent","consent_version"]}]},"AiTopupRequest":{"type":"object","properties":{"amount_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"billing_consent":{"const":true},"auto_topup":{"type":"object","properties":{"threshold_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"amount_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"monthly_limit_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"approved_api_client_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"billing_consent":{"const":true},"consent_version":{"const":"ai-auto-topup-v1"}},"required":["threshold_usd","amount_usd","monthly_limit_usd","approved_api_client_id","billing_consent","consent_version"],"additionalProperties":false}},"required":["amount_usd","billing_consent"],"additionalProperties":false},"AiConfigureRequest":{"type":"object","properties":{"resource":{"type":"string","enum":["access","auto_topup"]},"config":{"type":"object","additionalProperties":true}},"required":["resource","config"],"additionalProperties":false,"oneOf":[{"properties":{"resource":{"const":"access"},"config":{"$ref":"#/components/schemas/AiAccessRequest"}}},{"properties":{"resource":{"const":"auto_topup"},"config":{"$ref":"#/components/schemas/AiAutoTopupRequest"}}}]},"AiTextRequest":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid","description":"Opaque TokPortal resource ID. Never a provider task ID."},"max_cost_usd":{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]{1,6})?$","example":"2.500000","description":"Non-negative USD decimal string, up to six fractional digits. Never a credit count or binary floating-point amount."},"stream":{"type":"boolean","default":false}},"required":["quote_id","max_cost_usd"],"additionalProperties":false}}},"x-tokportal":{"schemaStatus":"partial-foundation","canonicalBaseUrl":"https://app.tokportal.com/api/ext","intendedConsumers":["docs","typescript-sdk","python-sdk","go-sdk","cli","mcp"]}}