{"components":{"parameters":{"IdempotencyKey":{"description":"Optional, at most 200 bytes. Scoped to the account across all its keys. Same key and normalized request returns the original task (202); different content returns 409. Use a new value for each intended generation; reuse it on uncertain network retries. Applies only to generation endpoints.","in":"header","name":"Idempotency-Key","required":false,"schema":{"maxLength":200,"type":"string"}},"ProviderID":{"in":"path","name":"providerId","required":true,"schema":{"description":"Connection ID returned by the administrative provider list.","type":"string"}},"TaskID":{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}},"responses":{"BadRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid request or provider configuration"},"Forbidden":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Insufficient key permissions, personal account required, or cross-origin browser mutation rejected."},"NotFound":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource not found"},"ServiceUnavailable":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"A dependency prevented the operation"},"TooManyRequests":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Rolling request quota exceeded or local upload admission busy. Honor Retry-After in seconds.","headers":{"Retry-After":{"description":"Minimum seconds to wait before retrying.","schema":{"minimum":1,"type":"integer"}}}},"Unauthorized":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Missing or invalid Gateway API key"}},"schemas":{"APIKey":{"properties":{"created_at":{"format":"date-time","type":"string"},"created_by":{"description":"User who issued the key.","format":"uuid","readOnly":true,"type":"string"},"expires_at":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"last_used_at":{"description":"Approximate usage time, updated at most once per minute.","format":"date-time","type":"string"},"name":{"type":"string"},"organization_id":{"description":"Omit for a personal key. Organization keys require current membership and use shared providers.","format":"uuid","type":"string"},"prefix":{"description":"Short recognizable prefix; cannot authenticate.","type":"string"},"resource_mode":{"description":"Personal without organization_id; shared with organization_id. The provider source must match the key ownership.","enum":["personal","shared"],"type":"string"},"revoked_at":{"description":"Present after permanent revocation.","format":"date-time","type":"string"},"scopes":{"items":{"enum":["generation","system:manage","organizations:manage","providers:manage","storage:manage","keys:manage"],"type":"string"},"type":"array"},"user_id":{"description":"Immutable key recipient; organization membership and issuer permissions are required. Defaults to the issuer.","format":"uuid","type":"string"}},"required":["id","name","prefix","scopes","created_at"],"type":"object"},"APIKeyList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/APIKey"},"type":"array"}},"required":["data"],"type":"object"},"APIKeyMonthlyUsage":{"properties":{"actual_usd":{"description":"Confirmed charges only; incomplete while unconfirmed_tasks is nonzero.","type":"number"},"api_key_id":{"format":"uuid","type":"string"},"consumed_usd":{"description":"Known generation cost before package coverage; consumes organization balance and member weekly allowance.","type":"number"},"estimated_cost_usd":{"description":"Sum of available USD cost estimates, including any usage already reported by pending tasks. Does not include tasks with unknown cost.","minimum":0,"type":"number"},"expected_usd":{"description":"Sum of immutable admission estimates.","type":"number"},"month":{"example":"2026-09","type":"string"},"package_covered_usd":{"description":"Tariff value of bill-confirmed package units; does not reduce consumption.","type":"number"},"pending_tasks":{"description":"Queued or running tasks; their final usage may not yet be known.","minimum":0,"type":"integer"},"tasks":{"minimum":0,"type":"integer"},"unconfirmed_tasks":{"minimum":0,"type":"integer"},"unknown_cost_tasks":{"description":"Finished tasks without a USD cost estimate. These are not free tasks.","minimum":0,"type":"integer"}},"required":["api_key_id","month","estimated_cost_usd","tasks","pending_tasks","unknown_cost_tasks"],"type":"object"},"AdminProvider":{"description":"Configuration belongs to the authenticated account. Secret fields are masked. Connection checks can contact the provider to verify inference access. Separate billing credentials are used to retrieve actual generation charges.","properties":{"api_type":{"description":"Adapter type shared by independent connections.","type":"string"},"archived":{"description":"Stops new work while retaining accepted tasks and history.","type":"boolean"},"base_url":{"type":"string"},"billing_access_key_hint":{"readOnly":true,"type":"string"},"billing_configured":{"type":"boolean"},"billing_help":{"type":"string"},"check_latency_ms":{"format":"int64","type":"integer"},"configured":{"type":"boolean"},"connection":{"$ref":"#/components/schemas/ProviderConnection"},"credential_hint":{"readOnly":true,"type":"string"},"credential_source":{"type":"string"},"default_timeout_seconds":{"description":"Installation default used when connection.timeout_seconds is unset.","format":"int64","type":"integer"},"description":{"type":"string"},"enabled":{"type":"boolean"},"fields":{"items":{"$ref":"#/components/schemas/ProviderField"},"type":"array"},"hints":{"additionalProperties":{"type":"string"},"description":"Masked hints only for secret fields.","type":"object"},"icon_monochrome":{"type":"boolean"},"icon_url":{"description":"Module-owned raster or original vector asset URL.","type":"string"},"id":{"type":"string"},"last_checked_at":{"format":"date-time","type":"string"},"media_counts":{"additionalProperties":{"type":"integer"},"type":"object"},"model_count":{"type":"integer"},"models":{"items":{"$ref":"#/components/schemas/MediaModel"},"type":"array"},"music_base_url":{"type":"string"},"music_configured":{"type":"boolean"},"music_credential_hint":{"readOnly":true,"type":"string"},"name":{"type":"string"},"region":{"type":"string"},"status":{"type":"string"},"status_message":{"type":"string"},"supports_billing_credentials":{"description":"Whether separate billing credentials are supported.","type":"boolean"},"updated_at":{"format":"date-time","type":"string"},"values":{"additionalProperties":{"type":"string"},"description":"Non-secret saved settings.","type":"object"},"version":{"description":"Current version required when changing connection configuration, name or archive state.","format":"int64","type":"integer"}},"required":["id","name","description","enabled","configured","credential_source","billing_configured","status","status_message","model_count","media_counts","updated_at"],"type":"object"},"AuditEvent":{"properties":{"action":{"type":"string"},"actor_email":{"type":"string"},"actor_id":{"type":"string"},"actor_name":{"type":"string"},"actor_picture":{"format":"uri","type":"string"},"actor_type":{"enum":["user","service"],"type":"string"},"calling_key_id":{"type":"string"},"correlation_id":{"type":"string"},"created_at":{"format":"date-time","type":"string"},"details":{"additionalProperties":true,"description":"Safe change details. Organization managers receive restricted=true for Administrator-only changes; mixed changes omit internal fields.","type":"object"},"id":{"minimum":1,"type":"integer"},"legacy_id":{"type":"integer"},"legacy_source":{"type":"string"},"object_id":{"type":"string"},"object_name":{"type":"string"},"object_picture":{"description":"Current profile image when the audited object is a user.","format":"uri","type":"string"},"object_type":{"type":"string"},"organization_id":{"type":"string"},"organization_name":{"type":"string"},"outcome":{"enum":["success","denied","failed"],"type":"string"},"schema_version":{"type":"integer"},"scope":{"enum":["system","organization","personal"],"type":"string"}},"required":["id","created_at","schema_version","scope","action","object_type","object_id","outcome","details"],"type":"object"},"AuditEventPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AuditEvent"},"type":"array"},"has_more":{"type":"boolean"},"next_before_id":{"type":"integer"}},"type":"object"},"BalanceEntry":{"additionalProperties":false,"properties":{"amount_usd":{"description":"Signed balance change for this entry; zero for attempts without a credit","type":"number"},"created_at":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"kind":{"enum":["payment","promo","adjustment","attempt"],"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"},"provider":{"type":"string"},"reason":{"type":"string"}},"required":["id","created_at","amount_usd","kind","reason","provider"],"type":"object"},"BonusEntry":{"properties":{"actor_id":{"type":"string"},"actor_name":{"type":"string"},"actor_picture":{"format":"uri","type":"string"},"amount_usd":{"description":"Signed ledger amount; payouts are negative.","type":"number"},"beneficiary":{"enum":["manager","supervisor"],"type":"string"},"created_at":{"format":"date-time","type":"string"},"employee_id":{"format":"uuid","type":"string"},"id":{"format":"int64","type":"integer"},"kind":{"enum":["accrual","correction","payout"],"type":"string"},"method":{"type":"string"},"paid_at":{"format":"date","type":"string"},"reason":{"type":"string"},"task_id":{"format":"uuid","type":"string"}},"type":"object"},"BonusSettings":{"additionalProperties":false,"properties":{"manager_percent":{"default":5,"maximum":100,"minimum":0,"multipleOf":0.01,"type":"number"},"starts_at":{"description":"Only requests accepted after activation participate.","format":"date-time","readOnly":true,"type":"string"},"supervisor_percent":{"default":1,"maximum":100,"minimum":0,"multipleOf":0.01,"type":"number"},"version":{"minimum":1,"type":"integer"}},"required":["manager_percent","supervisor_percent","version"],"type":"object"},"BrandAsset":{"additionalProperties":false,"properties":{"data":{"description":"Base64-encoded image bytes up to 512 KiB decoded","format":"byte","type":"string"},"mime":{"enum":["image/png","image/jpeg","image/svg+xml"],"type":"string"}},"required":["mime","data"],"type":"object"},"BrandPalette":{"additionalProperties":false,"properties":{"accent":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"accent-dark":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"accent-text":{"description":"Accent foreground text and selection/focus edges; inherits accent in legacy palettes.","pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"bg":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"blue":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"chart-1":{"description":"Primary chart series; inherits accent in legacy palettes.","pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"chart-2":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"chart-3":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"chart-4":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"chart-5":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"chart-6":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"field":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"highlight":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"line":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"muted":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"on-accent":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"on-highlight":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"on-warning":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"panel":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"panel-2":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"popup":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"red":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"success":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"switch-off":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"switch-on-border":{"description":"On switch edge; inherits accent in legacy palettes.","pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"switch-thumb":{"description":"Off switch thumb; inherits on-accent in legacy palettes.","pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"switch-thumb-on":{"description":"On switch thumb; inherits on-accent in legacy palettes.","pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"text":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"},"yellow":{"pattern":"^#[0-9a-fA-F]{6}$","type":"string"}},"required":["accent","accent-dark","highlight","on-accent","on-highlight","bg","panel","panel-2","field","popup","line","switch-off","text","muted","blue","red","success","yellow","on-warning","chart-2","chart-3","chart-4","chart-5","chart-6"],"type":"object"},"CatalogChange":{"properties":{"after":{},"before":{},"field":{"readOnly":true,"type":"string"},"model":{"readOnly":true,"type":"string"},"source":{"readOnly":true,"type":"string"}},"required":["model","field","source"],"type":"object"},"CatalogEntry":{"properties":{"contract":{"$ref":"#/components/schemas/MediaModel"},"id":{"readOnly":true,"type":"string"},"inactive":{"description":"Reviewed deactivated model retained for history, without an executable contract.","type":"boolean"},"metadata":{"$ref":"#/components/schemas/ModelMetadata"},"rates":{"items":{"$ref":"#/components/schemas/CatalogRate"},"type":"array"}},"required":["id"],"type":"object"},"CatalogObservation":{"properties":{"entries":{"items":{"$ref":"#/components/schemas/CatalogEntry"},"type":"array"},"error":{"readOnly":true,"type":"string"},"fetched_hash":{"description":"Snapshot of a fetched page that failed structured parsing; confirmed hash/candidates remain unchanged.","type":"string"},"hash":{"description":"Content-addressed source snapshot hash; synthetic _api uses parser api.","type":"string"},"review":{"description":"Code-reviewed acknowledgement of this exact successful document snapshot; later hashes require a new review.","properties":{"date":{"format":"date","type":"string"},"hash":{"type":"string"},"reason":{"type":"string"}},"readOnly":true,"required":["hash","date","reason"],"type":"object"},"source":{"oneOf":[{"$ref":"#/components/schemas/CatalogSource"},{"properties":{"id":{"const":"_api"},"parser":{"const":"api"},"url":{"type":"string"}},"required":["id","parser"],"type":"object"}]},"text":{"description":"Fetch-time only; omitted from state/run responses. Retrieve documents/{hash}.","type":"string"}},"required":["source","hash","entries"],"type":"object"},"CatalogRate":{"properties":{"audio":{"description":"Selects generated video audio; omitted means independent of audio.","type":"boolean"},"components":{"items":{"properties":{"estimated_units":{"type":"number"},"metric":{"readOnly":true,"type":"string"},"per":{"format":"int64","type":"integer"},"price":{"type":"number"}},"type":"object"},"type":"array"},"input_images":{"description":"Reviewed charge for reference images beyond the free allowance; frozen per task.","properties":{"free":{"minimum":0,"type":"integer"},"price":{"minimum":0,"type":"number"}},"required":["free","price"],"type":"object"},"per":{"format":"int64","type":"integer"},"price":{"description":"USD unit price, preserved to six decimal places.","type":"number"},"quality":{"readOnly":true,"type":"string"},"region":{"readOnly":true,"type":"string"},"resolution":{"readOnly":true,"type":"string"},"source":{"readOnly":true,"type":"string"},"unit":{"readOnly":true,"type":"string"},"video_input":{"description":"Selects reference-video tariffs; omitted or false means no video input.","type":"boolean"}},"type":"object"},"CatalogRun":{"properties":{"changes":{"items":{"$ref":"#/components/schemas/CatalogChange"},"type":"array"},"completed_at":{"format":"date-time","readOnly":true,"type":"string"},"email_status":{"enum":["not_needed","disabled","pending","retry","sent","failed"],"type":"string"},"id":{"format":"uuid","type":"string"},"new_warnings":{"items":{"$ref":"#/components/schemas/CatalogWarning"},"type":"array"},"open_warnings":{"items":{"$ref":"#/components/schemas/CatalogWarning"},"type":"array"},"provider":{"readOnly":true,"type":"string"},"resolved_warnings":{"items":{"$ref":"#/components/schemas/CatalogWarning"},"type":"array"},"sources":{"items":{"$ref":"#/components/schemas/CatalogObservation"},"type":"array"},"started_at":{"format":"date-time","readOnly":true,"type":"string"},"status":{"enum":["unchanged","applied","warning","error"],"type":"string"},"version":{"format":"int64","type":"integer"}},"required":["id","provider","started_at","completed_at","status","version","changes","new_warnings","open_warnings","resolved_warnings","sources","email_status"],"type":"object"},"CatalogSchedule":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"last_check":{"format":"date-time","readOnly":true,"type":"string"},"next_check":{"format":"date-time","readOnly":true,"type":"string"},"provider":{"readOnly":true,"type":"string"},"requested":{"description":"Read-only queued manual check indicator.","readOnly":true,"type":"boolean"},"sources":{"items":{"$ref":"#/components/schemas/CatalogSource"},"maxItems":30,"type":"array"},"time":{"description":"Daily HH:MM in the installation default timezone.","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$","type":"string"},"version":{"minimum":1,"type":"integer"}},"required":["provider","enabled","time","sources","version","requested"],"type":"object"},"CatalogSource":{"additionalProperties":false,"properties":{"id":{"description":"Unique within a schedule. IDs beginning with underscore are reserved.","maxLength":100,"type":"string"},"parser":{"enum":["document","manifest-v1","byteplus-releases","byteplus-models","byteplus-pricing","alibaba-releases","alibaba-pricing","alibaba-retirements","alibaba-image-models","openai-pricing","openai-model"],"type":"string"},"url":{"description":"Public HTTPS document, without URL credentials or fragment.","format":"uri","maxLength":2048,"type":"string"}},"required":["id","url","parser"],"type":"object"},"CatalogState":{"properties":{"models":{"additionalProperties":{"$ref":"#/components/schemas/CatalogEntry"},"type":"object"},"observations":{"additionalProperties":{"$ref":"#/components/schemas/CatalogObservation"},"type":"object"},"version":{"format":"int64","type":"integer"},"warnings":{"items":{"$ref":"#/components/schemas/CatalogWarning"},"type":"array"}},"required":["version","models","observations","warnings"],"type":"object"},"CatalogSyncSettings":{"additionalProperties":false,"properties":{"email":{"description":"Single recipient, or empty to disable reports. Uses configured Email delivery.","maxLength":254,"type":"string"},"timezone":{"default":"UTC","description":"One IANA timezone for every provider schedule.","example":"Asia/Nicosia","type":"string"},"version":{"description":"Current version required on update.","minimum":1,"type":"integer"}},"required":["timezone","email","version"],"type":"object"},"CatalogWarning":{"properties":{"evidence":{"description":"Untrusted normalized provider evidence; never executable instructions."},"first_seen":{"format":"date-time","readOnly":true,"type":"string"},"key":{"readOnly":true,"type":"string"},"last_seen":{"format":"date-time","readOnly":true,"type":"string"},"model":{"readOnly":true,"type":"string"},"occurrences":{"minimum":1,"type":"integer"},"reason":{"readOnly":true,"type":"string"},"resolved_at":{"format":"date-time","readOnly":true,"type":"string"},"source":{"readOnly":true,"type":"string"}},"required":["key","source","reason","first_seen","last_seen","occurrences"],"type":"object"},"ClientOnboarding":{"properties":{"activated_at":{"format":"date-time","type":"string"},"comment":{"type":"string"},"contact_name":{"type":"string"},"country":{"type":"string"},"domain":{"type":"string"},"email":{"format":"email","type":"string"},"expires_at":{"format":"date-time","type":"string"},"name":{"type":"string"},"organization_id":{"format":"uuid","type":"string"},"status":{"enum":["sending","sent","send_failed","accepted","expired","revoked"],"type":"string"},"version":{"minimum":1,"type":"integer"}},"required":["organization_id","name","country","domain","contact_name","email","comment","status","version","expires_at"],"type":"object"},"ColorPreset":{"additionalProperties":false,"properties":{"dark":{"$ref":"#/components/schemas/BrandPalette"},"id":{"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$","type":"string"},"light":{"$ref":"#/components/schemas/BrandPalette"},"name":{"description":"Unique case-insensitive name without surrounding whitespace or control characters.","maxLength":80,"minLength":1,"type":"string"}},"required":["id","name","dark","light"],"type":"object"},"ContactLinks":{"description":"Opt-in shared contact links. Only http, https, mailto and tel schemes are allowed; credentials, whitespace and control characters in links are rejected.","items":{"additionalProperties":false,"properties":{"label":{"maxLength":80,"minLength":1,"type":"string"},"url":{"description":"Absolute HTTP(S)","limited to 2048 UTF-8 bytes.":null,"mailto or tel link":null,"maxLength":2048,"type":"string"}},"required":["label","url"],"type":"object"},"maxItems":20,"type":"array"},"CreateAPIKeyRequest":{"additionalProperties":false,"properties":{"created_by":{"description":"User who issued the key.","format":"uuid","readOnly":true,"type":"string"},"expires_at":{"description":"Optional future timestamp. Omit for no expiration; revoked keys always stop authenticating.","format":"date-time","type":"string"},"name":{"description":"A recognizable name, e.g. Production bot.","maxLength":80,"minLength":1,"type":"string"},"organization_id":{"description":"Omit for a personal key. Organization keys require current membership and use shared providers.","format":"uuid","type":"string"},"resource_mode":{"description":"Personal without organization_id; shared with organization_id. The provider source must match the key ownership.","enum":["personal","shared"],"type":"string"},"scopes":{"default":["generation"],"description":"generation is required. Only a current administrator may request system:manage. Add providers:manage, storage:manage and/or keys:manage explicitly. A calling key cannot grant permissions it does not have.","items":{"enum":["generation","system:manage","organizations:manage","providers:manage","storage:manage","keys:manage"],"type":"string"},"type":"array"},"user_id":{"description":"Immutable key recipient; organization membership and issuer permissions are required. Defaults to the issuer.","format":"uuid","type":"string"}},"required":["name"],"type":"object"},"CreatedAPIKey":{"properties":{"created_at":{"format":"date-time","type":"string"},"created_by":{"description":"User who issued the key.","format":"uuid","readOnly":true,"type":"string"},"expires_at":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"last_used_at":{"description":"Approximate usage time, updated at most once per minute.","format":"date-time","type":"string"},"name":{"type":"string"},"organization_id":{"description":"Omit for a personal key. Organization keys require current membership and use shared providers.","format":"uuid","type":"string"},"prefix":{"description":"Short recognizable prefix; cannot authenticate.","type":"string"},"resource_mode":{"description":"Personal without organization_id; shared with organization_id. The provider source must match the key ownership.","enum":["personal","shared"],"type":"string"},"revoked_at":{"description":"Present after permanent revocation.","format":"date-time","type":"string"},"scopes":{"items":{"enum":["generation","system:manage","organizations:manage","providers:manage","storage:manage","keys:manage"],"type":"string"},"type":"array"},"secret":{"description":"Full bearer secret, returned only in this creation response. Save it now; it cannot be retrieved later.","type":"string"},"user_id":{"description":"Immutable key recipient; organization membership and issuer permissions are required. Defaults to the issuer.","format":"uuid","type":"string"}},"required":["id","name","prefix","scopes","created_at","secret"],"type":"object"},"EmailDeliverySettings":{"properties":{"available_providers":{"items":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"type":"object"},"type":"array"},"enabled":{"description":"A provider","sender and key are saved; not a guarantee of successful delivery.":null,"type":"boolean"},"from":{"type":"string"},"key_configured":{"type":"boolean"},"provider":{"enum":["","resend"],"type":"string"},"version":{"format":"int64","type":"integer"}},"required":["provider","from","key_configured","enabled","version","available_providers"],"type":"object"},"ErrorResponse":{"properties":{"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"},"param":{"description":"Invalid field when known.","type":["string","null"]},"type":{"description":"OpenAI-style error category.","type":"string"}},"required":["code","message","type","param"],"type":"object"}},"required":["error"],"type":"object"},"ExternalPaymentSettlement":{"additionalProperties":false,"properties":{"amount_cents":{"maximum":1000000,"minimum":100,"type":"integer"},"currency":{"enum":["usd"],"type":"string"},"external_id":{"maxLength":128,"minLength":1,"type":"string"},"fee_cents":{"minimum":0,"type":"integer"},"held_cents":{"minimum":0,"type":"integer"},"organization_id":{"format":"uuid","type":"string"},"refunded_cents":{"minimum":0,"type":"integer"},"revision":{"minimum":1,"type":"integer"}},"required":["organization_id","external_id","amount_cents","currency","revision"],"type":"object"},"Generation":{"description":"Always asynchronous. Keeps task extensions (options, cost, usage, storage and webhook metadata). Statuses and Unix timestamps match the OpenAI video vocabulary. Costs pass through the same customer/admin financial projection. content_url requires the same Gateway API key. No progress percentage is invented. Managers receive operational metadata only, with content_access false and without prompt, input, output links or provider errors.","properties":{"background":{"type":"string"},"can_delete":{"description":"Whether this viewer may delete stored result files.","type":"boolean"},"completed_at":{"description":"Result archival time if recorded; null until known.","type":["integer","null"]},"content_access":{"description":"Whether this viewer can inspect retained content.","type":"boolean"},"content_url":{"type":"string"},"cost":{"$ref":"#/components/schemas/TaskCost"},"created_at":{"format":"int64","type":"integer"},"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":["object","null"]},"has_stored_result":{"type":"boolean"},"id":{"type":"string"},"image":{"items":{"type":"string"},"type":"array"},"input":{"type":"string"},"input_reference":{"items":{"type":"string"},"type":"array"},"instructions":{"type":"string"},"media_type":{"$ref":"#/components/schemas/MediaType"},"model":{"type":"string"},"object":{"enum":["video","generation"],"type":"string"},"options":{"$ref":"#/components/schemas/MediaOptions"},"output_format":{"type":"string"},"prompt":{"type":"string"},"provider":{"type":"string"},"provider_model":{"description":"Native provider model ID for provenance","type":"string"},"quality":{"type":"string"},"response_format":{"type":"string"},"result_deleted_at":{"format":"date-time","type":"string"},"seconds":{"type":"string"},"size":{"type":"string"},"status":{"enum":["queued","in_progress","completed","failed"],"type":"string"},"status_url":{"type":"string"},"timeout_seconds":{"description":"Explicit generation HTTP timeout override","format":"int64","type":"integer","when supplied.":null},"updated_at":{"format":"int64","type":"integer"},"usage":{"$ref":"#/components/schemas/ProviderUsage"},"user_id":{"description":"Request recipient account, including in redacted metadata.","type":"string"},"voice":{"type":"string"}},"required":["id","object","status","created_at","updated_at","status_url"],"type":"object"},"GenerationImageInput":{"description":"Image URL, an object containing exactly image_url or file_id (from /v1/references), or a nonempty array. File IDs are checked against the authenticated owner. Models advertising supports_asset_references also accept asset://ID strings (or image_url values) for registered provider assets, mixed with URLs in the same ordered array. These IDs are not Gateway file_id values. Multipart file uploads are also supported for edits/videos.","oneOf":[{"type":"string"},{"additionalProperties":false,"properties":{"image_url":{"type":"string"}},"required":["image_url"],"type":"object"},{"additionalProperties":false,"properties":{"file_id":{"type":"string"}},"required":["file_id"],"type":"object"},{"items":{"oneOf":[{"type":"string"},{"additionalProperties":false,"properties":{"file_id":{"type":"string"}},"required":["file_id"],"type":"object"},{"additionalProperties":false,"properties":{"image_url":{"type":"string"}},"required":["image_url"],"type":"object"}]},"minItems":1,"type":"array"}]},"GenerationRequest":{"additionalProperties":false,"description":"OpenAI-style naming with Gateway extensions. Use only fields appropriate for the media type. Standard fields are accepted only at the top level; only advertised options.parameters keys are accepted. JSON limit 64 KiB.","properties":{"background":{"type":"string"},"image":{"$ref":"#/components/schemas/GenerationImageInput"},"input":{"description":"Text to synthesize.","maxLength":10000,"type":"string"},"input_reference":{"$ref":"#/components/schemas/GenerationImageInput"},"instructions":{"type":"string"},"max_expected_cost_usd":{"description":"Gateway customer-price ceiling, including markup. Admission rejects a higher quote.","minimum":0,"type":"number"},"model":{"description":"Exact public ID from GET /v1/models. Defaults to provider/model and can be renamed by the administrator. Separate provider and media_type request fields are not accepted.","type":"string"},"n":{"description":"One image per asynchronous job.","enum":[1],"type":"integer"},"options":{"$ref":"#/components/schemas/MediaOptions"},"output_format":{"description":"Image output encoding supported by the model, e.g. png/jpeg/webp.","type":"string"},"prompt":{"description":"Text direction, subject to the model's limits. May be omitted or empty when prompt_optional or no_prompt is advertised; no_prompt rejects nonempty text.","maxLength":10000,"type":"string"},"quality":{"type":"string"},"response_format":{"description":"Speech audio encoding supported by the model; for images only url is supported. All endpoints return an asynchronous job, never immediate bytes/base64.","type":"string"},"seconds":{"description":"Video duration. Model-specific limits apply; no restriction to OpenAI durations.","pattern":"^[1-9][0-9]*$","type":"string"},"size":{"description":"Image WIDTHxHEIGHT (mapped to the provider catalog), or video WIDTHxHEIGHT mapped exactly to supported resolution and ratio. Catalog resolution strings are also accepted.","type":"string"},"stream":{"description":"All generations are asynchronous. Streaming is not supported.","enum":[false],"type":"boolean"},"timeout_seconds":{"description":"Gateway HTTP response deadline for generation submission, including body reading. Overrides connection.timeout_seconds; otherwise inherits the provider default (30 seconds). Does not change the asynchronous rendering lifetime. Persisted across worker restarts and part of idempotency matching. No automatic submission retries.","format":"int64","maximum":9223372036,"minimum":1,"type":"integer"},"voice":{"description":"Speech voice ID supported by the model.","type":"string"},"webhook_url":{"format":"uri","type":"string"}},"required":["model"],"type":"object"},"Health":{"properties":{"status":{"enum":["ok","unhealthy"],"type":"string"}},"required":["status"],"type":"object"},"LoginProvider":{"properties":{"client_id":{"type":"string"},"configured":{"type":"boolean"},"connected":{"type":"boolean"},"enabled":{"type":"boolean"},"name":{"type":"string"},"provider":{"enum":["google","email"],"type":"string"},"redirect_url":{"description":"Read-only callback derived from the trusted public origin","format":"uri","type":"string"},"secret_configured":{"type":"boolean"},"version":{"minimum":1,"type":"integer"}},"required":["provider","name","enabled","connected","configured","secret_configured","version"],"type":"object"},"MarkupConfig":{"additionalProperties":false,"properties":{"default_percent":{"description":"Null inherits system rules for a company. System default is required.","maximum":1000,"minimum":0,"multipleOf":0.01,"type":["number","null"]},"exceptions":{"items":{"$ref":"#/components/schemas/MarkupRule"},"maxItems":500,"type":"array"},"version":{"format":"int64","minimum":1,"type":"integer"}},"required":["default_percent","exceptions","version"],"type":"object"},"MarkupPercent":{"description":"Percentage added to shared-provider cost. 25 means a 25% markup.","maximum":1000,"minimum":0,"multipleOf":0.01,"type":"number"},"MarkupPolicy":{"properties":{"company":{"description":"Organization configuration; version is zero when no organization is selected.","properties":{"default_percent":{"type":["number","null"]},"exceptions":{"items":{"$ref":"#/components/schemas/MarkupRule"},"type":"array"},"version":{"format":"int64","minimum":0,"type":"integer"}},"type":"object"},"system":{"$ref":"#/components/schemas/MarkupConfig"}},"type":"object"},"MarkupRule":{"additionalProperties":false,"properties":{"markup_percent":{"$ref":"#/components/schemas/MarkupPercent"},"model":{"description":"Omit or use an empty string for all models of the provider.","maxLength":256,"type":"string"},"provider":{"maxLength":100,"minLength":1,"type":"string"}},"required":["provider","markup_percent"],"type":"object"},"MediaAccess":{"properties":{"download_url":{"type":"string"},"expires_at":{"format":"date-time","type":"string"},"last_frame_url":{"description":"Signed browser URL for an archived video last frame, when available.","type":"string"},"preview_url":{"type":"string"}},"required":["preview_url","download_url","expires_at"],"type":"object"},"MediaModel":{"description":"Discover capabilities at runtime. Lists, requirements, pricing and supported options vary by provider, account and model.","properties":{"audio_always_on":{"description":"The model does not offer a silent-generation switch. Omit generate_audio or set it to true.","type":"boolean"},"backgrounds":{"items":{"type":"string"},"type":"array"},"default_duration":{"type":"integer"},"display_name":{"type":"string"},"draft_resolutions":{"items":{"type":"string"},"type":"array"},"duration_from_input":{"description":"Output duration follows the input media; omit seconds and options.duration.","type":"boolean"},"duration_step":{"description":"Allowed duration increments, starting at min_duration. Omitted means one second.","type":"integer"},"formats":{"items":{"type":"string"},"type":"array"},"id":{"type":"string"},"max_duration":{"type":"integer"},"max_image_inputs":{"type":"integer"},"max_seed":{"description":"Model-specific upper bound for options.seed.","type":"integer"},"media_type":{"$ref":"#/components/schemas/MediaType"},"metadata":{"$ref":"#/components/schemas/ModelMetadata"},"min_duration":{"type":"integer"},"min_image_inputs":{"type":"integer"},"no_instructions":{"type":"boolean"},"no_language":{"type":"boolean"},"no_prompt":{"description":"The model operates on media inputs without a text prompt. Omit prompt or use an empty string.","type":"boolean"},"no_seed":{"description":"When true, omit options.seed.","type":"boolean"},"no_watermark":{"description":"When true, omit options.watermark.","type":"boolean"},"parameters":{"items":{"$ref":"#/components/schemas/ParameterField"},"type":"array"},"pricing":{"$ref":"#/components/schemas/ModelPricing"},"prompt_optional":{"description":"The model accepts an empty prompt, for example when direction comes from reference media.","type":"boolean"},"public_id":{"description":"Public model identifier used for generation requests","type":"string"},"qualities":{"items":{"type":"string"},"type":"array"},"ratios":{"items":{"type":"string"},"type":"array"},"reference_modes":{"description":"Allowed reference combinations; shared by server validation and the console.","items":{"properties":{"id":{"type":"string"},"image_roles":{"description":"Labels assigned to images by position; remaining images are ordinary references.","items":{"type":"string"},"type":"array"},"label":{"type":"string"},"max_audios":{"type":"integer"},"max_images":{"type":"integer"},"max_videos":{"type":"integer"},"max_visuals":{"description":"Combined image/video limit, if set.","type":"integer"},"min_audios":{"type":"integer"},"min_images":{"type":"integer"},"min_videos":{"type":"integer"},"requires_visual":{"description":"Audio requires at least one image or video.","type":"boolean"},"supports_reference_voice":{"type":"boolean"}},"type":"object"},"type":"array"},"reference_prompt_syntax":{"description":"UI hint for ordered Image N or Agnes \u003cPicture N\u003e prompt previews. Does not rewrite the prompt or enable provider asset management. Wan first_frame_references numbers reference images after the first frame.","enum":["numbered","picture"],"type":"string"},"requires_audio_input":{"type":"boolean"},"requires_image_input":{"type":"boolean"},"requires_video_input":{"type":"boolean"},"requires_voice":{"type":"boolean"},"resolutions":{"items":{"type":"string"},"type":"array"},"supports_asset_references":{"description":"Accepts registered provider asset://ID references for image, video and audio inputs allowed by reference_modes. Assets must be ready and accessible to the configured provider account and project.","type":"boolean"},"supports_audio":{"type":"boolean"},"supports_audio_input":{"type":"boolean"},"supports_camera_fixed":{"type":"boolean"},"supports_draft":{"type":"boolean"},"supports_gender":{"type":"boolean"},"supports_image_input":{"type":"boolean"},"supports_last_frame":{"type":"boolean"},"supports_lyrics":{"type":"boolean"},"supports_negative_prompt":{"type":"boolean"},"supports_video_input":{"type":"boolean"},"supports_voice":{"type":"boolean"},"voices":{"items":{"type":"string"},"type":"array"}},"required":["id","display_name","media_type","resolutions","ratios","min_duration","max_duration","default_duration","supports_audio","supports_draft","supports_camera_fixed","supports_last_frame","pricing"],"type":"object"},"MediaOptions":{"additionalProperties":false,"properties":{"audio_urls":{"description":"Audio references or driving audio according to the selected mode. Models advertising supports_asset_references also accept asset://ID entries, mixed with URLs.","items":{"format":"uri","type":"string"},"type":"array"},"camera_fixed":{"description":"Fixed camera; omit if supports_camera_fixed is false.","type":"boolean"},"draft":{"description":"Preview generation when supports_draft is true; use draft_resolutions when listed.","type":"boolean"},"duration":{"description":"Music or audio output duration in seconds, when advertised by the model. Video requests use the top-level seconds field. Fractional effects may declare a number parameter instead.","minimum":0,"type":"integer"},"format":{"description":"Output format from the model’s formats list.","type":"string"},"gender":{"description":"Vocal gender when supports_gender is true.","enum":["female","male"],"type":"string"},"generate_audio":{"description":"Request synchronized audio when supports_audio is true.","type":"boolean"},"language":{"description":"Speech language, subject to the model; for example English or Auto.","type":"string"},"lyrics":{"description":"Music lyrics when supports_lyrics is true.","type":"string"},"negative_prompt":{"description":"Exclusions for models with supports_negative_prompt.","type":"string"},"parameters":{"additionalProperties":true,"description":"Additional controls declared by MediaModel.parameters. Unknown keys and invalid types are rejected.","type":"object"},"ratio":{"description":"Video aspect ratio from the catalog, for example 16:9.","type":"string"},"reference_mode":{"description":"Select an ID from the model's reference_modes. This determines image order and native roles. If omitted, the model selects its default reference mode. first_frame_references uses its first image as the first frame; remaining images are ordinary references.","type":"string"},"reference_voices":{"additionalProperties":{"format":"uri","type":"string"},"description":"Wan 2.7 reference-to-video only. Maps an ordinary image/video URL to its voice audio URL. First frames cannot have a voice. WAV or MP3, 1–10 seconds, at most 15 MB. Defaults to the reference video's original voice when omitted.","type":"object"},"return_last_frame":{"description":"Return the final video frame when supports_last_frame is true.","type":"boolean"},"seed":{"description":"Video random seed from 0 to 4294967295; omit for provider randomness.","format":"int64","maximum":4294967295,"minimum":0,"type":"integer"},"video_urls":{"description":"Video references in order. Models advertising supports_asset_references also accept asset://ID entries, mixed with URLs. Respect the selected reference mode's count limits.","items":{"format":"uri","type":"string"},"type":"array"},"watermark":{"description":"Provider watermark preference, subject to provider support.","type":"boolean"}},"type":"object"},"MediaType":{"enum":["image","video","speech","music","audio"],"type":"string"},"ModelMetadata":{"description":"Reviewed metadata plus account API metadata. Provider financial facts and source links are included only for administrators. Dates may have day or month precision; API object creation is not a release date. Provider capabilities can exceed those exposed by this gateway.","properties":{"api_created":{"description":"Unix timestamp returned by the provider model API.","format":"int64","type":"integer"},"checked_at":{"format":"date","type":"string"},"description":{"type":"string"},"facts":{"items":{"properties":{"label":{"type":"string"},"value":{"type":"string"}},"type":"object"},"type":"array"},"owned_by":{"type":"string"},"release_date":{"example":"2026-09-08","type":"string"},"shutdown_date":{"type":"string"},"snapshot":{"type":"string"},"sources":{"items":{"properties":{"title":{"type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"},"type":"array"},"version_date":{"example":"2026-09-08","type":"string"}},"type":"object"},"ModelPricing":{"description":"Reference price is the gateway price including current organization markup. Provider unit-rate fields are administrator-only.","properties":{"draft_audio_factor":{"type":"number"},"draft_silent_factor":{"type":"number"},"known":{"type":"boolean"},"reference_description":{"type":"string"},"reference_price_usd":{"type":"number"},"reference_quote":{"$ref":"#/components/schemas/TaskCost"},"usd_per_million_audio_tokens":{"type":"number"},"usd_per_million_by_resolution":{"additionalProperties":{"type":"number"},"type":"object"},"usd_per_million_tokens":{"type":"number"}},"type":"object"},"ModelSetting":{"properties":{"capabilities":{"$ref":"#/components/schemas/MediaModel"},"enabled_by_default":{"type":"boolean"},"granted":{"description":"Explicit grant for the organization being read","type":"boolean"},"id":{"format":"uuid","type":"string"},"model":{"description":"Native provider model ID","type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"provider_icon_monochrome":{"description":"Whether the provider artwork should follow the active theme","type":"boolean"},"provider_icon_url":{"description":"Content-versioned provider artwork URL for administrative model pickers","type":"string"},"provider_name":{"description":"Provider display name in administrative catalog responses","type":"string"},"public_id":{"description":"Exact model value used in generation requests","type":"string"},"version":{"type":"integer"}},"type":"object"},"OpenAIModel":{"properties":{"capabilities":{"$ref":"#/components/schemas/MediaModel"},"created":{"description":"Provider API creation timestamp when available; null otherwise. This is not a release date.","type":["integer","null"]},"id":{"type":"string"},"object":{"const":"model","type":"string"},"owned_by":{"type":"string"},"provider":{"type":"string"}},"required":["id","object","created","owned_by","provider","capabilities"],"type":"object"},"Organization":{"properties":{"available_usd":{"multipleOf":0.000001,"type":"number"},"balance_usd":{"multipleOf":0.000001,"type":"number"},"created_at":{"format":"date-time","type":"string"},"credit_limit_usd":{"multipleOf":0.000001,"type":"number"},"default_weekly_limit_usd":{"maximum":1000000,"minimum":0,"type":["number","null"]},"domain":{"description":"Normalized main website hostname; empty for historical companies without a website.","type":"string"},"effective_markup_percent":{"allOf":[{"$ref":"#/components/schemas/MarkupPercent"}],"description":"Base fallback rate before provider/model exceptions; returned only to administrators. Use markup rules to determine a specific model rate.","readOnly":true},"id":{"type":"string"},"markup_percent":{"description":"Administrators only. Null or omitted in a response means inherit system rules; zero overrides system rates. Company provider/model exceptions still take priority.","maximum":1000,"minimum":0,"multipleOf":0.01,"type":["number","null"]},"minimize_request_logging":{"description":"New generations discard request content after completion when true. The default is false.","type":"boolean"},"name":{"type":"string"},"role":{"enum":["supermanager","admin","content_officer","developer","member","system_admin","client_manager"]},"storage_bytes":{"type":"integer"},"usage":{"description":"Customer-only summary for view=summary and roles with statistics access. Uses the report charge calculation; balance remains current.","properties":{"last_activity_at":{"description":"Latest accepted generation across all dates and providers including free and pending requests. Null means never used.","format":"date-time","type":["string","null"]},"spend_usd":{"description":"Known customer charges in the selected period.","multipleOf":0.000001,"type":"number"},"unknown_costs":{"description":"Completed requests with an unknown charge in the period.","type":"integer"}},"type":"object"},"weekly_committed_usd":{"multipleOf":0.000001,"type":"number"},"weekly_limit_usd":{"maximum":1000000,"minimum":0,"type":["number","null"]}},"type":"object"},"OrganizationCredit":{"properties":{"actor_id":{"type":"string"},"amount_usd":{"multipleOf":0.000001,"type":"number"},"created_at":{"format":"date-time","type":"string"},"external_id":{"type":"string"},"id":{"type":"string"},"kind":{"type":"string"},"reason":{"type":"string"}},"type":"object"},"OrganizationInvitation":{"properties":{"accepted_by":{"type":["string","null"]},"accepted_by_email":{"description":"Email of the user who accepted this invitation. Included in the organization invitation list when accepted.","format":"email","type":"string"},"already_member":{"description":"True when the caller is already an active member. Open the organization without accepting the invitation again.","type":"boolean"},"expires_at":{"format":"date-time","type":"string"},"first_owner":{"description":"Recipient-bound onboarding invitation for the first Supermanager, rather than an ordinary selected-role invitation.","type":"boolean"},"id":{"type":"string"},"organization_id":{"type":"string"},"organization_name":{"type":"string"},"revoked_at":{"type":["string","null"]},"role":{"description":"Organization role granted on acceptance; Member for legacy ordinary invitations.","enum":["supermanager","admin","content_officer","developer","member"],"type":"string"},"token":{"description":"Shown once on creation. Stored as a hash.","type":"string"}},"type":"object"},"OrganizationMember":{"properties":{"contacts":{"$ref":"#/components/schemas/ContactLinks"},"email":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"picture":{"format":"uri","type":"string"},"role":{"enum":["supermanager","admin","content_officer","developer","member"]},"total_consumed_usd":{"description":"Known generation costs for this member in this organization, across all time.","multipleOf":0.000001,"type":"number"},"weekly_committed_usd":{"multipleOf":0.000001,"type":"number"},"weekly_limit_usd":{"maximum":1000000,"minimum":0,"type":["number","null"]}},"type":"object"},"OrganizationModelAccess":{"additionalProperties":false,"properties":{"model_ids":{"items":{"format":"uuid","type":"string"},"maxItems":10000,"type":"array","uniqueItems":true},"version":{"minimum":1,"type":"integer"}},"required":["model_ids","version"],"type":"object"},"ParameterField":{"properties":{"choices":{"items":{"type":"string"},"type":"array"},"default":{},"key":{"pattern":"^[a-z][a-z0-9_]*$","type":"string"},"label":{"type":"string"},"max":{"type":"number"},"max_length":{"type":"integer"},"min":{"type":"number"},"required":{"type":"boolean"},"type":{"enum":["text","select","boolean","number","integer"],"type":"string"}},"required":["key","label","type"],"type":"object"},"Payment":{"additionalProperties":false,"properties":{"amount_cents":{"description":"Top-up principal before tax and processing fees, in USD cents.","type":"integer"},"billing":{"$ref":"#/components/schemas/PaymentBilling"},"checkout_url":{"format":"uri","type":"string"},"created_at":{"format":"date-time","type":"string"},"credited_cents":{"type":"integer"},"currency":{"enum":["usd"],"type":"string"},"expires_at":{"description":"Payment request deadline at creation plus 30 days. Unpaid requests become expired and cannot be reused.","format":"date-time","type":"string"},"fee_cents":{"description":"Processor fee in cents. Stablecoin payment fees are stored separately in stablecoin.fee_micros, without cent rounding.","type":"integer"},"fee_micros":{"description":"Exact payment fee in USD millionths across payment methods","minimum":0,"type":"integer"},"fee_mode":{"enum":["service","organization"],"type":"string"},"held_cents":{"type":"integer"},"id":{"format":"uuid","type":"string"},"invoice":{"$ref":"#/components/schemas/PaymentInvoice"},"invoice_mode":{"enum":["","stripe","local"],"type":"string"},"live":{"type":"boolean"},"organization_id":{"format":"uuid","type":"string"},"provider_id":{"format":"uuid","type":"string"},"receipt_url":{"format":"uri","type":"string"},"refunded_cents":{"type":"integer"},"revision":{"type":"integer"},"settled":{"type":"boolean"},"settlement":{"$ref":"#/components/schemas/PaymentSettlement"},"stablecoin":{"$ref":"#/components/schemas/StablecoinPayment"},"status":{"enum":["pending","confirming","cancelled","paid","partially_refunded","refunded","disputed","expired","failed"],"type":"string"},"tax_mode":{"description":"Empty for legacy or external payments; exclusive for new card and stablecoin top-ups.","enum":["","exclusive"],"type":"string"},"updated_at":{"format":"date-time","type":"string"},"vat":{"$ref":"#/components/schemas/PaymentVATSnapshot"}},"required":["id","organization_id","provider_id","amount_cents","currency","live","status","fee_mode","fee_cents","credited_cents","settled","revision"],"type":"object"},"PaymentBilling":{"description":"Verified purchase basis and customer billing details. Tax is paid by the customer and never credited to their balance. Refund and hold amounts here include tax; payment-level refunded_cents and held_cents are principal reductions.","properties":{"address":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"postal_code":{"type":"string"},"state":{"type":"string"}},"type":"object"},"business_name":{"type":"string"},"email":{"type":"string"},"held_cents":{"minimum":0,"type":"integer"},"refunded_cents":{"minimum":0,"type":"integer"},"subtotal_cents":{"minimum":100,"type":"integer"},"tax_cents":{"minimum":0,"type":"integer"},"tax_ids":{"items":{"properties":{"type":{"type":"string"},"value":{"type":"string"}},"type":"object"},"type":"array"},"total_cents":{"minimum":100,"type":"integer"}},"type":"object"},"PaymentCheckout":{"additionalProperties":false,"properties":{"amount_usd":{"maximum":10000,"minimum":1,"multipleOf":0.01,"type":"number"},"billing":{"$ref":"#/components/schemas/StablecoinBillingProfile"},"fee_mode":{"enum":["service","organization"],"type":"string"},"network":{"enum":["ethereum","bsc","polygon"],"type":"string"},"provider_id":{"format":"uuid","type":"string"},"token":{"enum":["USDT","USDC"],"type":"string"}},"required":["provider_id","amount_usd","fee_mode"],"type":"object"},"PaymentInvoice":{"description":"Native Stripe invoice or a locally issued immutable PDF. Native documents may remain pending after settlement; local documents are generated on request.","properties":{"id":{"type":"string"},"number":{"type":"string"},"pdf_url":{"format":"uri","type":"string"},"status":{"enum":["pending","paid","issued"],"type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"},"PaymentNotificationSettings":{"additionalProperties":false,"properties":{"critical_emails":{"items":{"format":"email","type":"string"},"type":"array"},"delivery":{"additionalProperties":false,"properties":{"last_sent_at":{"description":"Last acceptance by the email provider; not proof of inbox delivery","format":"date-time","type":"string"},"pending":{"minimum":0,"type":"integer"},"retrying":{"minimum":0,"type":"integer"}},"required":["pending","retrying"],"type":"object"},"email_enabled":{"type":"boolean"},"success_emails":{"items":{"format":"email","type":"string"},"type":"array"},"version":{"minimum":1,"type":"integer"}},"required":["critical_emails","success_emails","version","email_enabled","delivery"],"type":"object"},"PaymentNotificationUpdate":{"additionalProperties":false,"properties":{"critical_emails":{"items":{"format":"email","maxLength":254,"type":"string"},"maxItems":20,"type":"array"},"success_emails":{"items":{"format":"email","maxLength":254,"type":"string"},"maxItems":20,"type":"array"},"version":{"minimum":1,"type":"integer"}},"required":["critical_emails","success_emails","version"],"type":"object"},"PaymentProvider":{"additionalProperties":false,"properties":{"account_id":{"type":"string"},"credentials_configured":{"type":"boolean"},"enabled":{"type":"boolean"},"fee_mode":{"enum":["service","organization"],"type":"string"},"id":{"format":"uuid","type":"string"},"kind":{"enum":["stripe","stablecoin","external"],"type":"string"},"last_webhook_at":{"format":"date-time","type":"string"},"live":{"type":"boolean"},"name":{"type":"string"},"stablecoin":{"$ref":"#/components/schemas/StablecoinConfig"},"stripe_invoices":{"default":true,"description":"Stripe only. Enable native Stripe invoice creation; disable for local VAT and Gateway PDF invoices. Omitted on update preserves the saved value. Changes apply to new payments.","type":"boolean"},"version":{"type":"integer"},"webhook_configured":{"type":"boolean"},"webhook_url":{"type":"string"}},"required":["id","kind","name","enabled","live","version","fee_mode"],"type":"object"},"PaymentProviderUpdate":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"fee_mode":{"enum":["service","organization"],"type":"string"},"kind":{"enum":["stripe","stablecoin"],"type":"string"},"name":{"maxLength":100,"type":"string"},"secret_key":{"maxLength":512,"type":"string","writeOnly":true},"stablecoin":{"$ref":"#/components/schemas/StablecoinConfig"},"stripe_invoices":{"default":true,"description":"Stripe only. Enable native Stripe invoice creation; disable for local VAT and Gateway PDF invoices. Omitted on update preserves the saved value. Changes apply to new payments.","type":"boolean"},"version":{"minimum":0,"type":"integer"},"webhook_secret":{"maxLength":512,"type":"string","writeOnly":true}},"required":["kind","name","enabled","fee_mode","version"],"type":"object"},"PaymentSellerCompany":{"additionalProperties":false,"properties":{"address":{"$ref":"#/components/schemas/PaymentBilling/properties/address"},"email":{"maxLength":254,"type":"string"},"invoice_logo":{"additionalProperties":false,"description":"Separate invoice logo. PNG or JPEG up to 512 KiB and 4 megapixels, max 4096 pixels per side. Re-encoded as PNG on save. Null removes it.","nullable":true,"properties":{"data":{"format":"byte","type":"string"},"mime":{"enum":["image/png","image/jpeg"],"type":"string"}},"required":["mime","data"],"type":"object"},"legal_name":{"maxLength":200,"minLength":1,"type":"string"},"oss_registered":{"type":"boolean"},"registration_number":{"maxLength":300,"type":"string"},"vat_number":{"description":"Seller VAT number. When VAT registered, 3–40 letters/digits including at least one digit; spaces are removed and letters uppercased on save. Invalid format returns invalid_seller_vat_number. The console derives VAT registration from a nonempty number; this does not verify registration with a tax authority.","maxLength":300,"type":"string"},"vat_registered":{"type":"boolean"}},"type":"object"},"PaymentSettlement":{"additionalProperties":false,"description":"Actual provider settlement amounts, not the cardholder bank debit. Divide minor-unit amounts by 10 to the power of decimal_places. Omitted until authoritative settlement data is available.","properties":{"amount_minor":{"minimum":1,"type":"integer"},"currency":{"pattern":"^[a-z]{3}$","type":"string"},"decimal_places":{"maximum":3,"minimum":0,"type":"integer"},"fee_minor":{"minimum":0,"type":"integer"}},"required":["currency","amount_minor","fee_minor","decimal_places"],"type":"object"},"PaymentVATRule":{"additionalProperties":false,"properties":{"country":{"description":"ISO country code or domestic/EU/non_eu/*","type":"string"},"rate_percent":{"maximum":100,"minimum":0,"multipleOf":0.01,"type":"number"},"status":{"enum":["any","registered","unregistered"],"type":"string"},"treatment":{"enum":["standard","reverse_charge","exempt","outside_scope"],"type":"string"}},"required":["country","status","treatment","rate_percent"],"type":"object"},"PaymentVATSettings":{"additionalProperties":false,"properties":{"rules":{"items":{"$ref":"#/components/schemas/PaymentVATRule"},"maxItems":500,"type":"array"},"seller":{"$ref":"#/components/schemas/PaymentSellerCompany"},"version":{"minimum":1,"type":"integer"}},"required":["version","seller","rules"],"type":"object"},"PaymentVATSnapshot":{"properties":{"buyer_country":{"type":"string"},"buyer_status":{"enum":["registered","unregistered","unverified"],"type":"string"},"rule":{"$ref":"#/components/schemas/PaymentVATRule"},"seller":{"$ref":"#/components/schemas/PaymentSellerCompany"},"settings_version":{"type":"integer"},"verification":{"$ref":"#/components/schemas/PaymentVATVerification"}},"type":"object"},"PaymentVATVerification":{"additionalProperties":false,"properties":{"business_name":{"type":"string"},"country":{"type":"string"},"expires_at":{"format":"date-time","type":"string"},"number":{"type":"string"},"reference":{"maxLength":1000,"type":"string"},"source":{"enum":["","manual","vies"],"readOnly":true,"type":"string"},"verified":{"type":"boolean"},"verified_at":{"format":"date-time","readOnly":true,"type":"string"},"version":{"minimum":0,"type":"integer"}},"type":"object"},"ProviderAsset":{"properties":{"asset_id":{"type":"string"},"error":{"description":"Sanitized registration/preparation failure.","type":"string"},"group_id":{"type":"string"},"name":{"type":"string"},"preview_url":{"description":"Temporary provider URL; never use as a durable identifier.","type":"string"},"status":{"description":"Provider state or Gateway preparation state; only Active is selectable.","type":"string"},"type":{"enum":["Image","Video","Audio"],"type":"string"},"uri":{"description":"asset:// ID for generation input once Active.","type":"string"}},"type":"object"},"ProviderAssetBinding":{"allOf":[{"$ref":"#/components/schemas/ProviderAsset"},{"properties":{"id":{"description":"Gateway workspace binding ID","format":"uuid","type":"string"},"provider":{"type":"string"},"registration_name":{"description":"Unique remote name used to reconcile uncertain creates","type":"string"},"source_id":{"format":"uuid","type":"string"},"updated_at":{"format":"date-time","type":"string"}},"type":"object"}]},"ProviderAssetBindings":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ProviderAssetBinding"},"type":"array"},"has_more":{"type":"boolean"},"next_offset":{"type":"integer"}},"type":"object"},"ProviderAssetGroup":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"ProviderAssetGroups":{"properties":{"can_import":{"type":"boolean"},"data":{"items":{"$ref":"#/components/schemas/ProviderAssetGroup"},"type":"array"}},"type":"object"},"ProviderAssetInventory":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ProviderAsset"},"type":"array"},"next":{"type":"string"}},"type":"object"},"ProviderConnection":{"description":"Administrator-managed API settings. Omitted connection preserves the existing object; when supplied it replaces it. Header values omitted on existing operation/name pairs preserve saved secrets. Manual models survive discovery refreshes. Unknown prices block budgeted generation until a per-request tariff is explicitly configured.","properties":{"endpoints":{"additionalProperties":false,"properties":{"generate":{"type":"string"},"models":{"type":"string"},"poll":{"description":"Task status URL or absolute path with a {task_id} placeholder.","type":"string"}},"type":"object"},"extra_body":{"additionalProperties":true,"description":"Optional body overrides; model and input content are protected.","type":"object"},"headers":{"items":{"properties":{"hint":{"readOnly":true,"type":"string"},"name":{"type":"string"},"operation":{"enum":["","models","generate","poll"],"type":"string"},"value":{"type":"string","writeOnly":true}},"required":["name"],"type":"object"},"maxItems":64,"type":"array"},"manual_catalog":{"description":"Skip remote discovery and use manual models only.","type":"boolean"},"models":{"items":{"properties":{"extra_body":{"additionalProperties":true,"type":"object"},"model":{"additionalProperties":true,"description":"Media model capabilities including exact upstream id, display_name and media_type.","type":"object"},"price_usd":{"description":"Explicit price per request. Omit for unknown pricing.","maximum":1000000,"minimum":0,"type":"number"},"profile":{"description":"ID of a supported API request profile from the types endpoint.","type":"string"}},"required":["model","profile"],"type":"object"},"maxItems":250,"type":"array"},"timeout_seconds":{"description":"API response deadline in seconds. Omit or null to inherit PROVIDER_HTTP_TIMEOUT (default 30 seconds). Generation timeout_seconds overrides it for submission only.","format":"int64","maximum":9223372036,"minimum":1,"type":["integer","null"]}},"type":"object"},"ProviderDescriptor":{"properties":{"credentials_configured":{"type":"boolean"},"default_model":{"type":"string"},"icon_monochrome":{"description":"Whether the artwork should follow the active theme","type":"boolean"},"icon_url":{"description":"Content-versioned module artwork URL","type":"string"},"id":{"type":"string"},"live":{"type":"boolean"},"models":{"items":{"$ref":"#/components/schemas/MediaModel"},"type":"array"},"name":{"type":"string"}},"required":["id","name","live","credentials_configured","default_model","models"],"type":"object"},"ProviderField":{"properties":{"default":{"type":"string"},"group":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"},"secret":{"type":"boolean"}},"required":["key","label"],"type":"object"},"ProviderUpdate":{"additionalProperties":{"type":"string","writeOnly":true},"description":"Fields are declared in AdminProvider.fields; unsupported keys are rejected. PUT acts as a partial update: omitted fields keep existing values; empty strings clear them. Clearing a required credential disables the provider. Billing credentials are optional and used only for charge reconciliation; clear both together. Raw credentials are never returned.","properties":{"api_key":{"description":"Write-only provider secret; omitted keeps the saved value; an empty string clears it.","type":"string","writeOnly":true},"archived":{"description":"Stops new work while retaining accepted tasks and history.","type":"boolean"},"asset_access_key_id":{"description":"Optional separate BytePlus library management AccessKey ID.","type":"string","writeOnly":true},"asset_access_key_secret":{"description":"Optional separate BytePlus library secret. Omit to preserve; empty clears.","type":"string","writeOnly":true},"asset_project":{"default":"default","description":"Library project; must match the inference endpoint project.","type":"string"},"asset_region":{"default":"ap-southeast-1","description":"Johor asset management region.","type":"string"},"base_url":{"description":"Provider endpoint override; omitted keeps the saved value; an empty string restores the default.","format":"uri","type":"string"},"billing_access_key_id":{"description":"Write-only provider secret; omitted keeps the saved value; an empty string clears it.","type":"string","writeOnly":true},"billing_access_key_secret":{"description":"Write-only provider secret; omitted keeps the saved value; an empty string clears it.","type":"string","writeOnly":true},"connection":{"$ref":"#/components/schemas/ProviderConnection"},"enabled":{"description":"Enable or disable this provider for the account.","type":"boolean"},"music_api_key":{"description":"Write-only provider secret; omitted keeps the saved value; an empty string clears it.","type":"string","writeOnly":true},"music_base_url":{"description":"Provider endpoint override; omitted keeps the saved value; an empty string restores the default.","format":"uri","type":"string"},"name":{"maxLength":120,"type":"string"},"version":{"description":"Current version required when changing connection configuration, name or archive state.","format":"int64","type":"integer"}},"type":"object"},"ProviderUsage":{"properties":{"cost_source":{"type":"string"},"cost_status":{"type":"string"},"currency":{"type":"string"},"estimated_cost":{"type":"number"},"metrics":{"items":{"properties":{"name":{"type":"string"},"quantity":{"type":"number"},"unit":{"type":"string"}},"required":["name","unit","quantity"],"type":"object"},"type":"array"},"raw":{"description":"Provider usage payload preserved as arbitrary JSON"}},"type":"object"},"ReferenceImage":{"properties":{"content_type":{"enum":["image/png","image/jpeg","image/webp","image/gif","video/mp4","video/quicktime","video/webm","audio/mpeg","audio/wave","audio/wav","audio/x-wav","audio/ogg","audio/flac"],"type":"string"},"created_at":{"format":"date-time","type":"string"},"duplicate":{"description":"True when upload reused an existing file.","type":"boolean"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"sha256":{"description":"SHA-256 of file bytes; optional for older images until indexed.","pattern":"^[0-9a-f]{64}$","type":"string"},"size_bytes":{"maximum":209715200,"minimum":1,"type":"integer"},"url":{"description":"Relative capability URL for preview and provider access. Treat it as a secret; anyone holding it can read the file until deletion or signing-key rotation.","type":"string"}},"required":["id","name","content_type","size_bytes","created_at","url"],"type":"object"},"ReportColumns":{"description":"Visible report columns. Omitted until the user saves a selection; the UI then uses its basic default set.","items":{"enum":["date","generation_id","organization","user","api_key","model","provider","status","tokens","estimated_cost","cost","confirmed_cost","settlement","customer_charge"],"type":"string"},"maxItems":14,"minItems":1,"type":"array","uniqueItems":true},"ReportDetail":{"properties":{"content_access":{"type":"boolean"},"generation":{"additionalProperties":true,"description":"Existing public generation representation restricted by viewer role","type":"object"},"links":{"description":"Report-scoped authenticated links for existing result files; content roles only","properties":{"content_url":{"type":"string"},"download_url":{"type":"string"},"last_frame_url":{"type":"string"}},"type":"object"},"processing":{"additionalProperties":true,"description":"Retained worker start","polling errors and original image-input flag; content roles only":null,"type":"object"},"report":{"additionalProperties":true,"and profit_recognized_at.":null,"awaiting_billing":null,"awaiting_cost":null,"description":"Authorized cost report row with user and key labels. Administrator and scoped sales viewers additionally receive profit_usd","not_applicable)":null,"not_tracked":null,"profit_status (generating":null,"recognized":null,"type":"object"},"request":{"description":"Content roles only. Minimal logging exposes only retained technical options.","properties":{"options":{"additionalProperties":true,"type":"object"},"prompt":{"type":"string"},"webhook_url":{"type":["string","null"]}},"type":"object"},"request_logging":{"enum":["full","minimized"],"type":"string"}},"required":["report","generation","content_access","request_logging"],"type":"object"},"ReportGroup":{"allOf":[{"$ref":"#/components/schemas/ReportMetrics"},{"properties":{"name":{"type":"string"},"provider":{"type":"string"}},"type":"object"}]},"ReportMetrics":{"properties":{"failed":{"type":"integer"},"pending_profit_requests":{"description":"Requests awaiting billing verification or known costs.","type":"integer"},"priced_requests":{"description":"Requests with known charge values.","type":"integer"},"profit_usd":{"description":"Administrator or scoped sales viewer only. Recognized customer spending minus provider cost; excludes deposits","historical requests and personal/BYOK requests.":null,"type":"number"},"recognized_profit_requests":{"type":"integer"},"requests":{"type":"integer"},"spend_usd":{"description":"Sum of known customer charges including markup; same amounts as report rows.","type":"number"},"successful":{"type":"integer"},"token_requests":{"description":"Requests that reported token counters; missing counters are not treated as zero.","type":"integer"},"tokens":{"description":"Reported total tokens; input/output counters are not added again when a total exists.","type":"number"}},"required":["requests","successful","failed","spend_usd","priced_requests","tokens","token_requests"],"type":"object"},"ReportSummary":{"allOf":[{"$ref":"#/components/schemas/ReportMetrics"},{"properties":{"average_cost_usd":{"description":"Average over requests with known costs.","type":["number","null"]},"interval":{"enum":["day","week","month"],"type":"string"},"periods":{"items":{"allOf":[{"$ref":"#/components/schemas/ReportMetrics"},{"properties":{"from":{"format":"date","type":"string"},"to":{"format":"date","type":"string"}},"type":"object"}]},"type":"array"},"provider_models":{"items":{"$ref":"#/components/schemas/ReportGroup"},"type":"array"},"providers":{"items":{"$ref":"#/components/schemas/ReportGroup"},"type":"array"},"public_models":{"description":"Historical public model names sorted by spend descending.","items":{"$ref":"#/components/schemas/ReportGroup"},"type":"array"}},"type":"object"}]},"RequestLimitConfig":{"additionalProperties":false,"properties":{"values":{"additionalProperties":false,"properties":{"key_generations_minute":{"example":100,"maximum":2147483647,"minimum":1,"nullable":true,"type":"integer"},"key_generations_second":{"example":20,"maximum":2147483647,"minimum":1,"nullable":true,"type":"integer"},"key_reads_minute":{"example":1200,"maximum":2147483647,"minimum":1,"nullable":true,"type":"integer"},"user_active_keys":{"example":20,"maximum":2147483647,"minimum":1,"nullable":true,"type":"integer"},"user_generations_minute":{"example":300,"maximum":2147483647,"minimum":1,"nullable":true,"type":"integer"},"user_generations_second":{"example":50,"maximum":2147483647,"minimum":1,"nullable":true,"type":"integer"},"user_key_creations_minute":{"example":5,"maximum":2147483647,"minimum":1,"nullable":true,"type":"integer"},"user_reads_minute":{"example":3600,"maximum":2147483647,"minimum":1,"nullable":true,"type":"integer"}},"required":["key_generations_minute","user_generations_minute","key_generations_second","user_generations_second","key_reads_minute","user_reads_minute","user_key_creations_minute","user_active_keys"],"type":"object"},"version":{"format":"int64","type":"integer"}},"required":["values","version"],"type":"object"},"RequestLimitPolicy":{"properties":{"effective":{"additionalProperties":{"minimum":1,"type":"integer"},"type":"object"},"organization":{"$ref":"#/components/schemas/RequestLimitConfig"},"system":{"$ref":"#/components/schemas/RequestLimitConfig"}},"required":["system","organization","effective"],"type":"object"},"RevokedKey":{"description":"Snapshot contains immutable alias, prefix, organization, owner/creator/revoker IDs and email labels, dates, scopes, expiry/resource settings, revocation reason, correlation ID, known spend in integer USD micros and pending/unknown counts at revocation. Budget is null because keys have no individual budgets. history_complete=false marks migrated records whose revoking actor and original spend were not recorded. Current lifetime values are separate and can change after reconciliation.","properties":{"current_spent_micros":{"type":"integer"},"id":{"format":"uuid","type":"string"},"organization_id":{"type":"string"},"pending_requests":{"type":"integer"},"revoked_at":{"format":"date-time","type":"string"},"snapshot":{"additionalProperties":true,"type":"object"},"unknown_cost_requests":{"type":"integer"}},"type":"object"},"RevokedKeyPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RevokedKey"},"type":"array"},"has_more":{"type":"boolean"},"next_offset":{"type":"integer"}},"type":"object"},"SalesGrant":{"properties":{"created_at":{"format":"date-time","type":"string"},"employee_id":{"format":"uuid","type":"string"},"id":{"format":"uuid","type":"string"},"issuer_id":{"format":"uuid","type":"string"},"issuer_name":{"type":"string"},"issuer_picture":{"format":"uri","type":"string"},"permission":{"enum":["pricing","models","topup","bonuses"],"type":"string"}},"type":"object"},"SalesMember":{"properties":{"email":{"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"own_clients":{"minimum":0,"type":"integer"},"picture":{"description":"Existing account profile picture; omitted when unavailable.","format":"uri","type":"string"},"role":{"$ref":"#/components/schemas/SalesRole"},"supervisor_id":{"description":"Empty means direct reporting to Administrator.","type":"string"}},"required":["id","name","email","role","supervisor_id","own_clients"],"type":"object"},"SalesRole":{"enum":["client_manager","lead_client_manager","regional_client_manager"],"type":"string"},"SalesStructure":{"properties":{"members":{"items":{"$ref":"#/components/schemas/SalesMember"},"type":"array"},"version":{"minimum":1,"type":"integer"}},"required":["version","members"],"type":"object"},"ServiceInfo":{"properties":{"auth_mode":{"description":"Console sign-in mode; personal keys remain valid in both modes.","enum":["google","api_key"],"type":"string"},"console":{"$ref":"#/components/schemas/SystemSettings"},"live":{"type":"boolean"},"model":{"type":"string"},"provider":{"type":"string"}},"required":["provider","model","live"],"type":"object"},"SiteBranding":{"additionalProperties":false,"properties":{"assets":{"additionalProperties":false,"description":"Dark slots use logo, symbol and favicon; corresponding light slots have _light suffix. Slots inherit from the other theme when empty. touch_icon and email_logo are shared.","properties":{"email_logo":{"$ref":"#/components/schemas/BrandAsset"},"favicon":{"$ref":"#/components/schemas/BrandAsset"},"favicon_light":{"$ref":"#/components/schemas/BrandAsset"},"logo":{"$ref":"#/components/schemas/BrandAsset"},"logo_light":{"$ref":"#/components/schemas/BrandAsset"},"symbol":{"$ref":"#/components/schemas/BrandAsset"},"symbol_light":{"$ref":"#/components/schemas/BrandAsset"},"touch_icon":{"$ref":"#/components/schemas/BrandAsset"}},"type":"object"},"contact_email":{"anyOf":[{"format":"email","maxLength":254,"type":"string"},{"maxLength":0,"type":"string"}],"description":"Empty when unconfigured; otherwise a valid contact email address."},"content_max_width":{"description":"Desktop content maximum in CSS pixels. Null uses all available content space.","maximum":7680,"minimum":640,"nullable":true,"type":"integer"},"dark":{"$ref":"#/components/schemas/BrandPalette"},"default_preset":{"description":"Existing color theme used on public surfaces and by users who follow the site default. The dark/light fields mirror this preset.","maxLength":64,"type":"string"},"description":{"description":"Maximum 240 UTF-8 bytes without control characters","maxLength":240,"type":"string"},"light":{"$ref":"#/components/schemas/BrandPalette"},"name":{"description":"Empty when unconfigured; otherwise maximum 80 UTF-8 bytes without control characters","maxLength":80,"type":"string"},"presets":{"description":"Administrator-managed named pairs of dark and light palettes. Legacy writes without this field preserve the catalog and edit its default pair.","items":{"$ref":"#/components/schemas/ColorPreset"},"maxItems":32,"minItems":1,"type":"array"},"sidebar_subsections":{"default":false,"description":"Expand navigation subsections in the left menu on desktop. Mobile retains horizontal tabs.","type":"boolean"},"site_max_width":{"default":1280,"description":"Desktop site maximum in CSS pixels. Null removes the width limit while retaining safe outer gutters. Missing legacy values retain 1280.","maximum":7680,"minimum":960,"nullable":true,"type":"integer"},"version":{"minimum":1,"type":"integer"}},"required":["name","description","contact_email","dark","light","assets","version"],"type":"object"},"StablecoinBillingProfile":{"additionalProperties":false,"properties":{"address":{"$ref":"#/components/schemas/PaymentBilling/properties/address"},"business_name":{"maxLength":200,"minLength":1,"type":"string"},"email":{"maxLength":300,"type":"string"},"tax_ids":{"$ref":"#/components/schemas/PaymentBilling/properties/tax_ids"}},"required":["business_name","address"],"type":"object"},"StablecoinConfig":{"additionalProperties":false,"properties":{"wallets":{"items":{"additionalProperties":false,"properties":{"address":{"pattern":"^0x[0-9a-fA-F]{40}$","type":"string"},"network":{"enum":["ethereum","bsc","polygon"],"type":"string"},"tokens":{"items":{"enum":["USDT","USDC"],"type":"string"},"maxItems":2,"minItems":1,"type":"array","uniqueItems":true}},"required":["network","address","tokens"],"type":"object"},"maxItems":3,"minItems":1,"type":"array"}},"required":["wallets"],"type":"object"},"StablecoinPayment":{"description":"Immutable transfer instructions and exact USD payment fee. One token unit is priced at one USD. Amount reservations survive payment and cancellation.","properties":{"address":{"type":"string"},"amount":{"pattern":"^[0-9]+\\.[0-9]{6}$","type":"string"},"block_number":{"type":"integer"},"contract":{"type":"string"},"explorer_url":{"format":"uri","type":"string"},"fee_micros":{"maximum":9999,"minimum":1,"type":"integer"},"log_index":{"type":"integer"},"network":{"enum":["ethereum","bsc","polygon"],"type":"string"},"start_block":{"minimum":0,"type":"integer"},"token":{"enum":["USDT","USDC"],"type":"string"},"transaction_hash":{"type":"string"},"vat":{"$ref":"#/components/schemas/PaymentVATSnapshot"}},"type":"object"},"StorageSettings":{"properties":{"access_key_id":{"description":"Saved key identifier, not the secret. Empty when no key is configured.","readOnly":true,"type":"string"},"browser_uploads_pending":{"description":"Present and true on Save when CORS was confirmed but browser access may still be propagating. Retry the read-only connection check; the policy does not need another write.","readOnly":true,"type":"boolean"},"bucket":{"type":"string"},"credentials_configured":{"type":"boolean"},"driver":{"enum":["local","s3","gateway"],"type":"string"},"endpoint":{"description":"HTTP(S) origin. Empty selects standard AWS endpoints.","type":"string"},"path_style":{"type":"boolean"},"prefix":{"type":"string"},"region":{"description":"Bucket region; auto for Cloudflare R2.","type":"string"}},"required":["driver","endpoint","region","bucket","prefix","path_style","access_key_id","credentials_configured"],"type":"object"},"StorageUpdate":{"additionalProperties":false,"properties":{"access_key_id":{"description":"Required for initial S3 setup and endpoint changes. Blank preserves saved value.","type":"string","writeOnly":true},"bucket":{"description":"Existing bucket, required for S3.","type":"string"},"driver":{"enum":["local","s3","gateway"],"type":"string"},"endpoint":{"description":"HTTP(S) origin without path, query or embedded credentials. A missing scheme defaults to HTTPS. Empty for AWS S3.","type":"string"},"path_style":{"default":false,"type":"boolean"},"prefix":{"maxLength":512,"type":"string"},"region":{"description":"Required for S3. Use auto for Cloudflare R2.","type":"string"},"secret_access_key":{"description":"Required for initial S3 setup and endpoint changes. Blank preserves saved value.","type":"string","writeOnly":true}},"required":["driver"],"type":"object"},"SystemSettings":{"additionalProperties":false,"properties":{"allow_inline_references":{"default":true,"description":"Allow reference contents in provider requests. When false, HTTP(S) URLs and model-supported asset:// references are accepted and library images are not inlined. Applies at admission and dispatch to shared and personal connections. Omission on update preserves the current value.","type":"boolean"},"generation_ui":{"description":"Show the Generation screen; does not disable API generation.","type":"boolean"},"markup_percent":{"allOf":[{"$ref":"#/components/schemas/MarkupPercent"}],"description":"Administrator setting; omitted from public console policy. Defaults to zero. Omission on update preserves the current rate. Applies only to new shared-provider tasks."},"personal_providers":{"description":"Let non-administrators manage personal provider connections. Personal keys cannot start new generations while this is disabled; saved connections and history are preserved.","type":"boolean"},"shared_resources":{"default":false,"description":"Enable shared providers and storage. Disabling blocks new shared work; accepted tasks and existing files remain available.","type":"boolean"},"shared_storage_limit_bytes":{"description":"Set through /v1/system/storage/quota; preserved by ordinary settings updates.","type":["integer","null"]},"version":{"description":"Send the current version when updating settings.","minimum":1,"type":"integer"}},"required":["generation_ui","personal_providers","version"],"type":"object"},"SystemUser":{"properties":{"created_at":{"format":"date-time","type":"string"},"email":{"type":"string"},"id":{"format":"uuid","type":"string"},"is_client_manager":{"type":"boolean"},"is_system_admin":{"type":"boolean"},"name":{"type":"string"},"picture":{"format":"uri","type":"string"},"sales_role":{"$ref":"#/components/schemas/SalesRole"}},"type":"object"},"SystemUserPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SystemUser"},"type":"array"},"has_more":{"type":"boolean"},"next_offset":{"type":"integer"}},"type":"object"},"TaskCost":{"description":"Customer responses expose gateway expected/metered/tariff amounts only (including accepted markup), plus quoted_at. Provider pricing, settlement and markup fields are returned only to administrators.","properties":{"actual_source":{"type":"string"},"actual_usd":{"description":"Confirmed paid USD charge, or confirmed free mock/failed generation. Omitted while unknown, never substituted with an estimate.","type":"number"},"billed_units":{"type":"number"},"billing_instance_id":{"type":"string"},"billing_match":{"description":"model_usage_window is an unambiguous model, time window, and usage quantity correlation, not a provider request ID match.","type":"string"},"billing_required":{"description":"Administrator-only accepted-quote snapshot; profit waits for provider bill verification when true.","type":"boolean"},"customer_expected_usd":{"description":"Expected customer price including the accepted markup; use for max_expected_cost_usd.","type":"number"},"customer_metered_usd":{"description":"Metered provider cost plus accepted markup, rounded up to a millionth of a dollar.","type":"number"},"customer_tariff_usd":{"description":"Reconciled gross provider cost plus accepted markup. Reports consumed_usd is the authoritative completed charge.","type":"number"},"estimated_units":{"type":"number"},"expected_usd":{"description":"Accepted gateway estimate for customers; original provider estimate for administrators.","type":"number"},"invoice_ids":{"items":{"type":"string"},"type":"array"},"markup_percent":{"allOf":[{"$ref":"#/components/schemas/MarkupPercent"}],"description":"Immutable accepted rate; absent on historical tasks means zero. Provider cost fields are not marked up."},"metered_usd":{"description":"Usage-based gateway cost for customers; original metered provider cost for administrators.","type":"number"},"package_units":{"description":"Units covered by a provider package; does not imply a daily quota or a free package.","type":"number"},"pricing":{"properties":{"bill_input_video":{"description":"Explicit duration-metering contract. True requires reported input and output video duration; false bills output only. Omitted on legacy snapshots, whose existing metering remains unchanged.","type":"boolean"},"checked_at":{"format":"date-time","type":"string"},"components":{"description":"Per-metric tariffs saved with the accepted task. Every component requires a reported metric before metering.","items":{"properties":{"estimated_units":{"description":"Planning quantity retained for synchronized tariff repricing.","type":"number"},"metric":{"type":"string"},"per":{"minimum":1,"type":"integer"},"price":{"type":"number"}},"required":["metric","price","per"],"type":"object"},"type":"array"},"currency":{"enum":["USD"],"type":"string"},"estimate_description":{"description":"Explanation of planning quantities and assumptions; not actual metered usage.","type":"string"},"fixed_usd":{"description":"Additional input-image charge for the accepted request.","type":"number"},"per":{"type":"integer"},"price":{"type":"number"},"region":{"type":"string"},"source":{"type":"string"},"unit":{"enum":["token","second","image","character","request","multi_metric"],"type":"string"},"version":{"type":"string"}},"required":["currency","unit","price","per","source","version","checked_at"],"type":"object"},"quoted_at":{"format":"date-time","type":"string"},"reconciled_at":{"format":"date-time","type":"string"},"status":{"enum":["estimated","pending_billing","confirmed"],"type":"string"},"submitted_at":{"format":"date-time","type":"string"},"tariff_usd":{"description":"Confirmed gateway cost for customers; original reconciled provider tariff for administrators.","type":"number"},"usage_recorded_at":{"format":"date-time","type":"string"}},"required":["expected_usd","customer_expected_usd","quoted_at"],"type":"object"},"User":{"properties":{"color_preset":{"description":"Personal color theme ID. Empty follows the site default; unavailable IDs render the site default.","maxLength":64,"type":"string"},"contacts":{"$ref":"#/components/schemas/ContactLinks"},"email":{"type":"string"},"id":{"format":"uuid","type":"string"},"is_client_manager":{"description":"Sales-account restriction shared by all three sales ranks.","type":"boolean"},"is_system_admin":{"description":"Current administrator access for this authentication method.","type":"boolean"},"name":{"type":"string"},"picture":{"type":"string"},"report_columns":{"$ref":"#/components/schemas/ReportColumns"},"sales_role":{"$ref":"#/components/schemas/SalesRole"},"session_id":{"description":"Opaque non-credential login identifier, present for browser sessions. Used to bind temporary console key storage to this login.","type":"string"},"theme":{"default":"system","enum":["dark","light","system"],"type":"string"}},"required":["id","email","name"],"type":"object"},"WebhookEvent":{"properties":{"created_at":{"format":"int64","type":"integer"},"data":{"$ref":"#/components/schemas/Generation"},"id":{"type":"string"},"object":{"const":"event","type":"string"},"type":{"enum":["generation.queued","generation.in_progress","generation.completed","generation.failed"],"type":"string"}},"required":["id","object","type","created_at","data"],"type":"object"},"WeeklyLimitUSD":{"description":"Member weekly USD limit. Null means unlimited; zero blocks paid shared generation. Resets Monday at 00:00 UTC.","maximum":1000000,"minimum":0,"multipleOf":0.000001,"type":["number","null"]}},"securitySchemes":{"bearerAuth":{"description":"Personal Gateway key (gw_…), or the separate deployment service key. An explicit key takes precedence over a browser session. Only Authorization Bearer is accepted.","scheme":"bearer","type":"http"},"paymentIntegrationAuth":{"description":"Dedicated pay_ token scoped to one trusted payment integration.","scheme":"bearer","type":"http"},"sessionAuth":{"description":"HttpOnly browser session for account, provider, storage and API-key administration only. Generation, catalog, task and reference endpoints require an API key, including in the console.","in":"cookie","name":"media_gateway_session","type":"apiKey"}}},"info":{"description":"One asynchronous API for image, video, speech and music generation. Connect providers once, then access your organization through the console or your applications. Generation endpoints use OpenAI vocabulary with asynchronous Gateway extensions. All creation returns a queued job, not immediate media. All generation routes share one contract; this is not drop-in synchronous SDK compatibility. Agnes AI image and video models use the same endpoints and catalog contract; select agnes/model-name from the model catalog. Provider key checks cannot verify Agnes access because its upstream model catalog is public.","license":{"identifier":"Apache-2.0","name":"Apache-2.0"},"title":"Media Gateway API","version":"0.4.0-preview"},"openapi":"3.1.0","paths":{"/auth/email/{action}":{"post":{"description":"JSON-only browser endpoint protected against cross-origin mutations. Register and forgot take email and optionally invitation_token. Both return a generic 202 and require configured email delivery. Verify exchanges its one-time token for a restricted HttpOnly registration cookie. Registration checks that cookie; complete sets a 15–128 character password and creates the account and normal session. Reset takes its one-time token and a new password. Verification expires in 1 hour; registration grants and reset in 30 minutes. Login takes email and password and sets an HttpOnly session cookie. Reset invalidates browser sessions and reset links, but not API keys. Email verification/reset tokens are delivered in URL fragments, submitted in JSON and never returned by this API. The optional invitation_token is encrypted in the challenge and restored only after proof of mailbox ownership through verify, registration, complete or reset responses. Registration grants cannot be substituted by JSON tokens. Invitation acceptance remains a separate authenticated action. Email-only registrations do not gain organization membership.","operationId":"post_auth_email","parameters":[{"in":"path","name":"action","required":true,"schema":{"enum":["register","login","forgot","verify","registration","complete","reset"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"email":{"format":"email","maxLength":254,"type":"string"},"invitation_token":{"description":"Optional organization invitation capability, accepted only by register/forgot. Restored after email ownership is verified; never accepted automatically.","maxLength":43,"minLength":43,"type":"string"},"password":{"format":"password","maxLength":128,"type":"string"},"token":{"maxLength":43,"minLength":43,"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"description":"Verified, reset or signed in. Verification/reset also returns the email."},"202":{"description":"Generic registration or recovery response; does not reveal account existence."},"400":{"description":"Invalid input, expired or already used link."},"401":{"description":"Incorrect email or password, or unverified address."},"403":{"description":"Cross-origin request rejected."},"415":{"description":"JSON content type required."},"429":{"description":"Too many attempts; Retry-After header supplied."},"503":{"description":"Delivery not configured, delivery failed, or authentication temporarily unavailable."}},"security":[],"summary":"Register, verify, sign in or recover an email account","tags":["Account"]}},"/auth/google":{"get":{"description":"Browser redirect to Google. Used to establish a console session and bootstrap the first key; no key required. Only registered when Google OAuth is configured.","operationId":"get_auth_google","responses":{"302":{"description":"Browser redirect"},"503":{"description":"Authentication unavailable"}},"security":[],"summary":"Start Google sign-in","tags":["Account"]}},"/auth/google/callback":{"get":{"description":"Browser callback with a one-time code and state. Validates identity, establishes an HttpOnly session and redirects to UI_PUBLIC_URL/. Only registered when Google OAuth is configured.","operationId":"get_auth_google_callback","parameters":[{"description":"Supplied by Google; do not construct manually.","in":"query","name":"code","schema":{"type":"string"}},{"description":"Supplied by Google; do not construct manually.","in":"query","name":"state","schema":{"type":"string"}},{"description":"Supplied by Google; do not construct manually.","in":"query","name":"error","schema":{"type":"string"}}],"responses":{"302":{"description":"Browser redirect"},"503":{"description":"Authentication unavailable"}},"security":[],"summary":"Complete Google sign-in","tags":["Account"]}},"/auth/logout":{"post":{"description":"Clears and invalidates the current session. Does not revoke personal API keys. Registered when browser authentication is configured.","operationId":"post_auth_logout","responses":{"204":{"description":"Signed out; empty response body"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[],"summary":"Sign out of the browser","tags":["Account"]}},"/auth/methods":{"get":{"operationId":"get_auth_methods","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"email":{"description":"Email sign-in is enabled and supported; password login does not require email delivery.","type":"boolean"},"email_confirmation":{"description":"Email authentication is enabled and supported; existing verification grants do not require current delivery availability.","type":"boolean"},"email_delivery":{"type":"boolean"},"google":{"type":"boolean"},"setup_required":{"description":"Fresh installation requires its one-time owner setup before ordinary sign-in. No setup code is exposed.","type":"boolean"}},"type":"object"}}},"description":"Availability only; never exposes email credentials."}},"security":[],"summary":"Available browser sign-in methods","tags":["Account"]}},"/auth/monitoring":{"get":{"description":"Cookie-only preflight for Grafana. Requires an active browser session and a current system Administrator role. API keys and caller-supplied identity headers cannot grant access. Browser authentication disabled is denied. The UI proxy uses the returned internal user ID only after a successful check; this header is not a reusable credential.","operationId":"get_monitoring_session","responses":{"204":{"description":"Current Administrator browser session","headers":{"X-WEBAUTH-USER":{"description":"Verified internal user ID for the private Grafana auth proxy","schema":{"type":"string"}}}},"401":{"description":"Browser sign-in required"},"403":{"description":"Administrator access required"},"503":{"description":"Administrator role could not be verified"}},"security":[{"sessionAuth":[]}],"summary":"Authorize the monitoring UI proxy","tags":["Account"]}},"/auth/session":{"get":{"description":"Cookie-only preflight for the UI file server. API keys do not establish browser sessions. Returns 204 when browser authentication is disabled.","operationId":"get_browser_session","responses":{"204":{"description":"Valid session or browser authentication disabled"},"401":{"description":"Browser sign-in required"}},"security":[],"summary":"Check browser session for frontend delivery","tags":["Account"]}},"/auth/setup":{"post":{"description":"JSON-only, cross-origin-protected initial setup. Requires the installation code obtained through trusted gateway admin setup-code. Only a fresh installation without users can be claimed. User, Administrator role, password, session and consumed setup code commit atomically. Email delivery is not required. Upgrades with existing users keep setup closed.","operationId":"post_auth_setup","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"code":{"maxLength":43,"minLength":43,"type":"string","writeOnly":true},"email":{"format":"email","maxLength":254,"type":"string"},"name":{"maxLength":100,"minLength":1,"type":"string"},"password":{"maxLength":128,"minLength":15,"type":"string","writeOnly":true}},"required":["code","name","email","password"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"message":{"type":"string"}},"type":"object"}}},"description":"Owner created and signed in through a Secure HttpOnly SameSite=Lax session cookie on HTTPS."},"400":{"description":"Invalid setup fields"},"403":{"description":"Invalid code or cross-origin request"},"409":{"description":"Initial setup unavailable or already completed"},"415":{"description":"JSON content type required"},"429":{"description":"Too many setup attempts"},"503":{"description":"Setup temporarily unavailable"}},"security":[],"summary":"Create the first installation owner and browser session","tags":["Account"]}},"/healthz":{"get":{"description":"Public readiness check for PostgreSQL and Redis. Does not verify provider credentials or model availability.","operationId":"get_healthz","responses":{"200":{"content":{"application/json":{"example":{"status":"ok"},"schema":{"$ref":"#/components/schemas/Health"}}},"description":"Dependencies are healthy"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}},"description":"A dependency is unhealthy"}},"security":[],"summary":"Check PostgreSQL and Redis health","tags":["System"]}},"/media/{id}":{"get":{"description":"Use the exact signed URL returned by media-access, without a Gateway key. Signature and expiry are required. Do not construct signatures in clients. Supports HEAD, Range and download=1.","operationId":"get_media_id","responses":{"200":{"content":{"audio/*":{"schema":{"format":"binary","type":"string"}},"image/*":{"schema":{"format":"binary","type":"string"}},"video/*":{"schema":{"format":"binary","type":"string"}}},"description":"Complete media object"},"206":{"description":"HTTP Range response"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid or expired URL"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[],"summary":"Access media through a temporary signed URL","tags":["Media"]},"head":{"description":"Use the exact signed URL returned by media-access, without a Gateway key. Signature and expiry are required. Do not construct signatures in clients. Supports HEAD, Range and download=1.","operationId":"head_media_id","responses":{"200":{"description":"Media headers"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"403":{"description":"Invalid or expired URL"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[],"summary":"Read signed media headers","tags":["Media"]},"parameters":[{"$ref":"#/components/parameters/TaskID"},{"description":"Expiry as a Unix timestamp","in":"query","name":"expires","required":true,"schema":{"format":"int64","type":"integer"}},{"in":"query","name":"signature","required":true,"schema":{"type":"string"}},{"in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}]},"/references/{owner}/{id}":{"get":{"description":"Use the URL returned by the library API; do not construct signatures. Possession grants read access until file deletion or MEDIA_URL_SIGNING_SECRET rotation. No session or bucket credentials are required. Supports HTTP ranges. Convert the relative URL to an absolute URL against this Gateway's public origin before passing it in image or input_reference.","operationId":"get_references_owner_id","responses":{"200":{"content":{"image/gif":{"schema":{"format":"binary","type":"string"}},"image/jpeg":{"schema":{"format":"binary","type":"string"}},"image/png":{"schema":{"format":"binary","type":"string"}},"image/webp":{"schema":{"format":"binary","type":"string"}}},"description":"Image bytes"},"206":{"description":"Requested byte range"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[],"summary":"Fetch a reference file using its capability URL","tags":["References"]},"head":{"operationId":"head_references_owner_id","responses":{"200":{"description":"Image headers without a response body"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[],"summary":"Inspect reference file headers","tags":["References"]},"parameters":[{"in":"path","name":"owner","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"signature","required":true,"schema":{"type":"string"}}]},"/site.json":{"get":{"description":"Public metadata used by independently served frontends. Assets include MIME metadata; download image bytes from /branding/assets/{asset}.","operationId":"get_site_configuration","responses":{"200":{"description":"API, UI and documentation origins plus branding settings. Empty origins use the current origin."}},"security":[],"summary":"Read public site origins and appearance","tags":["Account"]}},"/v1/admin/providers":{"get":{"description":" Requires providers:manage on personal keys, or a console session. Available when provider administration is configured.","operationId":"get_v1_admin_providers","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AdminProvider"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"Administrative provider catalog"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List every supported provider and its administrative state","tags":["Providers admin"],"x-required-scope":"providers:manage"},"post":{"description":"Requires a system administrator. Creates a disabled connection without testing credentials or making a paid request.","operationId":"post_v1_admin_providers","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"api_type":{"type":"string"},"name":{"maxLength":120,"type":"string"}},"required":["api_type","name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminProvider"}}},"description":"Created provider connection"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Create an independent provider connection","tags":["Providers admin"],"x-required-scope":"providers:manage"}},"/v1/admin/providers/types":{"get":{"description":"Requires a system administrator. Templates describe supported serialization formats; they do not imply access or pricing for manually added models.","operationId":"get_v1_admin_providers_types","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"fields":{"items":{"$ref":"#/components/schemas/ProviderField"},"type":"array"},"icon_monochrome":{"type":"boolean"},"icon_url":{"description":"Content-versioned module artwork URL","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"profiles":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"API types with connection fields and model capability templates"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List supported API adapters and request profile templates","tags":["Providers admin"],"x-required-scope":"providers:manage"}},"/v1/admin/providers/{providerId}":{"get":{"description":" Requires providers:manage on personal keys, or a console session. Available when provider administration is configured.","operationId":"get_v1_admin_providers_providerId","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminProvider"}}},"description":"Provider state"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Get provider configuration and live status","tags":["Providers admin"],"x-required-scope":"providers:manage"},"parameters":[{"$ref":"#/components/parameters/ProviderID"}],"put":{"description":"Omitted credential fields preserve the stored value; empty strings clear it. Clearing a required credential disables the provider. Requires providers:manage on personal keys, or a console session. Available when provider administration is configured.","operationId":"put_v1_admin_providers_providerId","requestBody":{"content":{"application/json":{"example":{"api_key":"YOUR_PROVIDER_API_KEY","enabled":true},"schema":{"$ref":"#/components/schemas/ProviderUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminProvider"}}},"description":"Updated and validated provider state"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Update credentials, endpoints, or enabled state","tags":["Providers admin"],"x-required-scope":"providers:manage"}},"/v1/admin/providers/{providerId}/check":{"parameters":[{"$ref":"#/components/parameters/ProviderID"}],"post":{"description":" Requires providers:manage on personal keys, or a console session. Available when provider administration is configured.","operationId":"post_v1_admin_providers_providerId_check","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminProvider"}}},"description":"Refreshed provider state"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Refresh provider model and connection status information","tags":["Providers admin"],"x-required-scope":"providers:manage"}},"/v1/admin/reports":{"get":{"description":"Personal generation history, including revoked personal keys. Organization-key credentials must use their organization report endpoint. Provider charge and package units remain separate. No charge is inferred when billing data is absent.","operationId":"get_v1_admin_reports","parameters":[{"description":"Aggregate all matching requests; ignores pagination. Cannot combine with CSV.","in":"query","name":"view","schema":{"enum":["summary"],"type":"string"}},{"description":"Summary calendar buckets in the selected timezone. Weeks start Monday. A range of one month or less has one monthly bucket. Maximum 10000 buckets.","in":"query","name":"interval","schema":{"default":"day","enum":["day","week","month"],"type":"string"}},{"description":"Exact user ID or email (case-insensitive); financial viewers only.","in":"query","name":"user","schema":{"type":"string"}},{"description":"IANA time zone for inclusive from/to calendar dates; CSV timestamps remain UTC.","in":"query","name":"timezone","schema":{"default":"UTC","type":"string"}},{"description":"Export every matching row as CSV; limit and offset are ignored.","in":"query","name":"format","schema":{"enum":["csv"],"type":"string"}},{"description":"First included date in the requested timezone; defaults to the start of this month.","in":"query","name":"from","schema":{"format":"date","type":"string"}},{"description":"Last included date in the requested timezone; defaults to today.","in":"query","name":"to","schema":{"format":"date","type":"string"}},{"in":"query","name":"api_key_id","schema":{"format":"uuid","type":"string"}},{"description":"Exact generation ID. Combined with the other filters.","in":"query","name":"generation_id","schema":{"format":"uuid","type":"string"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"maximum":100000,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ReportSummary"},{"properties":{"data":{"items":{"properties":{"api_key_id":{"type":["string","null"]},"api_key_name":{"type":"string"},"consumed_usd":{"description":"Generation cost before package coverage; null while unknown.","type":["number","null"]},"cost":{"$ref":"#/components/schemas/TaskCost"},"created_at":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"identity_historical":{"description":"True when labels were captured at request acceptance. False for legacy current-directory fallbacks.","type":"boolean"},"identity_snapshot":{"additionalProperties":true,"type":"object"},"model":{"type":"string"},"provider":{"type":"string"},"provider_name":{"type":"string"},"status":{"type":"string"},"usage":{"$ref":"#/components/schemas/ProviderUsage"}},"type":"object"},"type":"array"},"has_more":{"type":"boolean"},"next_offset":{"type":"integer"}},"type":"object"}]}},"text/csv":{"example":"Created at (UTC),Cost (USD)","schema":{"type":"string"}}},"description":"Tasks in descending creation order."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read personal cost history","tags":["Reports"],"x-required-scope":"keys:manage"}},"/v1/admin/reports/{id}":{"get":{"description":"Requires keys:manage for API keys; browser sessions are supported. Restricted to personal data, including revoked-key history. Organization-bound keys must use organization routes. Returns every retained public generation field and exact saved request settings when content access is allowed. Minimal logging omits prompt, instructions, webhook and references, exposing only retained resolution, ratio, duration and generate_audio. Customer views retain the existing financial sanitization. Provider/storage credentials are never returned.","operationId":"get_v1_admin_reports_id","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDetail"}}},"description":"Generation details authorized for this viewer"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No generation report in the authorized scope"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read full personal generation report","tags":["Reports"]}},"/v1/admin/reports/{id}/content":{"get":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"get_v1_admin_reports_id_content","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file content"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read personal generation result","tags":["Reports"]},"head":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"head_v1_admin_reports_id_content","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file headers"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Inspect personal generation result","tags":["Reports"]}},"/v1/admin/reports/{id}/last-frame":{"get":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"get_v1_admin_reports_id_last_frame","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file content"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read personal generation last frame","tags":["Reports"]},"head":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"head_v1_admin_reports_id_last_frame","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file headers"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Inspect personal generation last frame","tags":["Reports"]}},"/v1/admin/storage":{"get":{"description":"Returns the current local or S3 selection, connection fields and access key ID to authorized storage managers. The secret access key is never returned. Accounts default to local storage.","operationId":"get_v1_admin_storage","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageSettings"}}},"description":"Storage settings"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read account storage settings","tags":["Storage admin"],"x-required-scope":"storage:manage"},"put":{"description":"Tests S3 object write, read and delete permissions before activating. Checks browser preflights for configured UI_PUBLIC_URL (or API_PUBLIC_URL), falling back to the request Origin. Missing CORS is configured automatically using the saved key, preserving other rules and bucket privacy; CORS read/update rights are required only for missing browser access. After confirming the saved policy, browser_uploads_pending can be true while provider caches apply the change. Changes apply when results are archived, without restarting the worker. Existing files remain at their original location. Blank credentials preserve saved values; changing endpoint requires both credentials again. Selecting local preserves the last S3 connection. Maximum request body is 16 KiB.","operationId":"put_v1_admin_storage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageSettings"}}},"description":"Saved settings"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Configure account storage","tags":["Storage admin"],"x-required-scope":"storage:manage"}},"/v1/admin/storage/check":{"post":{"description":"Creates, reads and deletes a uniquely named temporary object under the configured prefix. Does not list or create buckets. Uses saved credentials if omitted. A successful check does not activate the settings. Also validates PUT/GET/HEAD browser preflights for configured UI_PUBLIC_URL (or API_PUBLIC_URL), falling back to the request Origin. Without either, retains the server-only probe. Missing browser access returns storage_browser_setup_required. No bucket CORS is changed.","operationId":"post_v1_admin_storage_check","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"status":{"const":"ok","type":"string"}},"type":"object"}}},"description":"Connection verified"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Test proposed storage settings without saving","tags":["Storage admin"],"x-required-scope":"storage:manage"}},"/v1/api-keys":{"get":{"description":"Includes active, expired and revoked keys. Never includes secrets or hashes. Requires a browser session or a personal key with keys:manage. The deployment service key cannot manage personal keys.","operationId":"get_v1_api_keys","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKeyList"}}},"description":"Account keys"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List account API keys","tags":["API keys"],"x-required-scope":"keys:manage"},"post":{"description":"Create the first key using your browser session. Thereafter a key with keys:manage may create keys with a subset of its own permissions. Body limit: 4 KiB. The secret is shown once. This operation is not idempotent; after an ambiguous timeout, inspect the key list and revoke an unused key before issuing a replacement. The deployment service key cannot manage personal keys.","operationId":"post_v1_api_keys","requestBody":{"content":{"application/json":{"example":{"name":"Production bot","scopes":["generation"]},"schema":{"$ref":"#/components/schemas/CreateAPIKeyRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedAPIKey"}}},"description":"Key created; save the secret now"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Request quota exceeded; no task was accepted. Retry after the indicated number of seconds. Limits use rolling windows and aggregate all keys of the user within the workspace.","headers":{"Retry-After":{"description":"Seconds until all exceeded quota windows allow another request","schema":{"minimum":1,"type":"integer"}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Create a personal API key","tags":["API keys"],"x-required-scope":"keys:manage"}},"/v1/api-keys/billing":{"get":{"description":"Owner-scoped billing import status. A successful import does not imply that aggregate bills can be matched to individual generation tasks.","operationId":"get_v1_api_keys_billing","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"checked_at":{"format":"date-time","type":"string"},"message":{"type":"string"},"provider":{"type":"string"},"status":{"enum":["synced","not_configured","error"],"type":"string"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"Last background synchronization per provider"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read provider billing synchronization status","tags":["API keys"],"x-required-scope":"keys:manage"}},"/v1/api-keys/usage":{"get":{"description":"Monthly spending statistics for account keys, including revoked keys. Financial limits belong to the organization and its members. consumed_usd includes only known completed gross generation costs; actual_usd includes only confirmed charges. Unknown legacy costs remain explicit. Tasks belong to their creation month in the requested timezone (UTC by default). Console session tasks have no API key attribution. Amounts use six decimal places.","operationId":"get_v1_api_keys_usage","parameters":[{"description":"Calendar month in the requested timezone, YYYY-MM (year 2000 or later). Defaults to the current month.","example":"2026-09","in":"query","name":"month","schema":{"pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$","type":"string"}},{"description":"IANA time zone for the calendar month. The console sends the user's local timezone.","in":"query","name":"timezone","schema":{"default":"UTC","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"currency":{"enum":["USD"],"type":"string"},"data":{"items":{"$ref":"#/components/schemas/APIKeyMonthlyUsage"},"type":"array"},"month":{"example":"2026-09","type":"string"}},"required":["data","month","currency"],"type":"object"}}},"description":"Monthly estimates and coverage by key"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read monthly spending by API key","tags":["API keys"],"x-required-scope":"keys:manage"}},"/v1/api-keys/{id}":{"delete":{"description":"Permanently blocks subsequent authentication. Repeating a revocation returns 204. Revocation does not cancel accepted tasks, revoke previously signed media URLs, or cascade to other keys created using this key. Requires a browser session or keys:manage. The deployment service key cannot manage personal keys.","operationId":"delete_v1_api_keys_id","responses":{"204":{"description":"Revoked; empty response body"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Revoke a personal API key","tags":["API keys"],"x-required-scope":"keys:manage"},"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}]},"/v1/audio/generations":{"post":{"description":"Returns HTTP 202 immediately after queue admission. Poll status_url until completed/failed; download content_url with the same API key. Provider execution never runs synchronously in this request. This endpoint selects media_type=music.","operationId":"post_v1_audio_generations","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}},"description":"Generation accepted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Budget exceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Idempotency conflict or changed estimate"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Pricing unavailable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Create music (Gateway extension)","tags":["Generations"],"x-required-scope":"generation"}},"/v1/audio/speech":{"post":{"description":"Returns HTTP 202 immediately after queue admission. Poll status_url until completed/failed; download content_url with the same API key. Provider execution never runs synchronously in this request. This endpoint selects media_type=speech.","operationId":"post_v1_audio_speech","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}},"description":"Generation accepted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Budget exceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Idempotency conflict or changed estimate"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Pricing unavailable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Create speech","tags":["Generations"],"x-required-scope":"generation"}},"/v1/audit/events":{"get":{"description":"Requires a current Administrator and a browser session or personal API key with system:manage. Organization-bound keys cannot read global history. Events contain safe changed fields, immutable identity labels and no credentials or request content. Historical snapshots never authorize access.","operationId":"get__v1_audit_events","parameters":[{"description":"First included calendar date in timezone, YYYY-MM-DD. Defaults to the first day of this month.","in":"query","name":"from","schema":{"type":"string"}},{"description":"Last included calendar date. Defaults to today. The backend uses an exclusive next-day boundary.","in":"query","name":"to","schema":{"type":"string"}},{"description":"IANA timezone; defaults to UTC.","in":"query","name":"timezone","schema":{"type":"string"}},{"description":"Exact organization ID; only filters global history. Scoped routes never widen access.","in":"query","name":"organization_id","schema":{"type":"string"}},{"description":"Actor ID, email or name; case-insensitive substring for names and email.","in":"query","name":"actor_id","schema":{"type":"string"}},{"description":"Exact action identifier.","in":"query","name":"action","schema":{"type":"string"}},{"description":"Exact object type.","in":"query","name":"object_type","schema":{"type":"string"}},{"description":"Exact object or key ID.","in":"query","name":"object_id","schema":{"type":"string"}},{"description":"success, denied or failed.","in":"query","name":"outcome","schema":{"type":"string"}},{"description":"system, organization or personal.","in":"query","name":"scope","schema":{"type":"string"}},{"description":"Exact server-generated correlation ID.","in":"query","name":"correlation_id","schema":{"type":"string"}},{"description":"Exclusive event ID cursor, not an offset; defaults to zero.","in":"query","name":"before_id","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventPage"}}},"description":"Safe history. Lists contain up to 50 rows."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List management audit events","tags":["Audit"],"x-required-scope":"system:manage"}},"/v1/audit/events/{event}":{"get":{"description":"Requires a current Administrator and a browser session or personal API key with system:manage. Organization-bound keys cannot read global history. Events contain safe changed fields, immutable identity labels and no credentials or request content. Historical snapshots never authorize access.","operationId":"get__v1_audit_events_event","parameters":[{"in":"path","name":"event","required":true,"schema":{"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEvent"}}},"description":"Safe history. Lists contain up to 50 rows."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Event not found in the permitted scope"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read one management audit event","tags":["Audit"],"x-required-scope":"system:manage"}},"/v1/audit/revoked-keys":{"get":{"description":"Requires a current Administrator and a browser session or personal API key with system:manage. Organization-bound keys cannot read global history. Events contain safe changed fields, immutable identity labels and no credentials or request content. Historical snapshots never authorize access.","operationId":"get__v1_audit_revoked_keys","parameters":[{"description":"First included calendar date in timezone, YYYY-MM-DD. Defaults to the first day of this month.","in":"query","name":"from","schema":{"type":"string"}},{"description":"Last included calendar date. Defaults to today. The backend uses an exclusive next-day boundary.","in":"query","name":"to","schema":{"type":"string"}},{"description":"IANA timezone; defaults to UTC.","in":"query","name":"timezone","schema":{"type":"string"}},{"description":"Exact organization ID; only filters global history. Scoped routes never widen access.","in":"query","name":"organization_id","schema":{"type":"string"}},{"description":"Actor ID, email or name; case-insensitive substring for names and email.","in":"query","name":"actor_id","schema":{"type":"string"}},{"description":"Exact object or key ID.","in":"query","name":"object_id","schema":{"type":"string"}},{"description":"Revoked-key history only; 0 to 100000.","in":"query","name":"offset","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokedKeyPage"}}},"description":"Safe history. Lists contain up to 50 rows."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List immutable revoked-key history","tags":["Audit"],"x-required-scope":"system:manage"}},"/v1/client-onboardings":{"get":{"description":"Browser only. Lists up to 100 recent cards currently in the manager's provisional or activated portfolio. Does not grant organization membership or statistics access before acceptance.","operationId":"get_client_onboardings","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ClientOnboarding"},"type":"array"}},"type":"object"}}},"description":"Scoped cards with invitation delivery status"},"403":{"description":"Not a client manager or explicit API credential"}},"security":[{"sessionAuth":[]}],"summary":"List companies onboarded by the current client manager","tags":["Organizations"]},"post":{"description":"Browser only. Atomically saves the company, provisional manager, recipient-bound 14-day Supermanager invitation and durable email delivery. Reuse operation_id and identical normalized input after an uncertain response. Creation success does not confirm email delivery. No user, password, credit, key or customer membership is created here.","operationId":"create_client_onboarding","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"comment":{"maxLength":2000,"type":"string"},"contact_name":{"maxLength":160,"minLength":1,"type":"string"},"country":{"maxLength":100,"minLength":1,"type":"string"},"domain":{"description":"Required company website or domain; normalized to hostname without www","maxLength":2048,"minLength":1,"port or path. Internationalized hostnames use ASCII IDNA.":null,"scheme":null,"type":"string"},"email":{"format":"email","maxLength":254,"type":"string"},"name":{"maxLength":160,"minLength":1,"type":"string"},"operation_id":{"format":"uuid","type":"string"}},"required":["operation_id","name","domain","country","contact_name","email"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientOnboarding"}}},"description":"Committed company or idempotent replay, including current delivery status"},"400":{"description":"Invalid fields"},"403":{"description":"Not a client manager or explicit API credential"},"409":{"description":"Reused operation with different input","or duplicate normalized name or website. Duplicate error includes criterion and manager; organization ID appears only within the caller's scope.":null},"429":{"description":"20 distinct companies changed within the rolling last hour"}},"security":[{"sessionAuth":[]}],"summary":"Create a company and email its first owner invitation","tags":["Organizations"]}},"/v1/client-onboardings/{org}/{action}":{"post":{"description":"Browser only, live provisional manager only. Reuse operation_id on uncertain retries. Version conflicts return 409. Resend preserves the company and invitation IDs, renews the 14-day expiry and rotates the link after successful delivery; revoked links stay invalid. Acceptance stops resend/revoke. Background delivery does not count toward the manual quota.","operationId":"change_first_owner_invitation","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"action","required":true,"schema":{"enum":["resend","revoke"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"operation_id":{"format":"uuid","type":"string"},"version":{"minimum":1,"type":"integer"}},"required":["operation_id","version"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientOnboarding"}}},"description":"Current card"},"403":{"description":"Outside current scope"},"409":{"description":"Version conflict","operation mismatch or invitation already accepted":null},"429":{"description":"Manual distinct-company limit reached"}},"security":[{"sessionAuth":[]}],"summary":"Resend or revoke an unaccepted first-owner invitation","tags":["Organizations"]}},"/v1/generations":{"get":{"description":"Gateway extension. Role-filtered jobs ordered by creation time and ID. Supports limit and offset; author filtering happens before pagination.","operationId":"list_generations","parameters":[{"in":"query","name":"offset","schema":{"default":0,"maximum":1000000,"minimum":0,"type":"integer"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Generation"},"type":"array"},"has_more":{"type":"boolean"},"next_offset":{"minimum":0,"type":"integer"},"object":{"const":"list"}},"type":"object"}}},"description":"Recent generations"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"List recent generations","tags":["Generations"]},"post":{"description":"Returns HTTP 202 immediately after queue admission. Poll status_url until completed/failed; download content_url with the same API key. Provider execution never runs synchronously in this request.","operationId":"post_v1_generations","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}},"description":"Generation accepted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Budget exceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Idempotency conflict or changed estimate"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Pricing unavailable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Create a generation (Gateway extension)","tags":["Generations"],"x-required-scope":"generation"}},"/v1/generations/estimate":{"post":{"description":"Estimate without creating or executing a generation. Same canonical input and model resolution as creation. Customer costs include markup.","operationId":"post_v1_generations_estimate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"can_generate":{"type":"boolean"},"cost":{"$ref":"#/components/schemas/TaskCost"},"remaining_usd":{"type":["number","null"]},"weekly_limit_usd":{"type":["number","null"]}},"type":"object"}}},"description":"Estimate"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Pricing unavailable"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Estimate a generation (Gateway extension)","tags":["Generations"],"x-required-scope":"generation"}},"/v1/generations/{id}":{"get":{"description":"Owner-scoped status. The video route returns 404 for other media types. All routes use the same statuses and Unix timestamps.","operationId":"get_v1_generations_id","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}},"description":"Generation"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Generation not found"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Retrieve asynchronous generation","tags":["Generations"]},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}]},"/v1/generations/{id}/content":{"delete":{"description":"Owner-scoped, generation-key authorization. Only terminal tasks may be deleted. Deletes result and last-frame files, including object versions, from the original destination. Metadata, prompt, provider URL and all accounting remain. Idempotent; retry a partial storage failure. Signed Gateway media URLs stop working after deletion. Provider links may already have expired.","operationId":"deleteGenerationResultFiles","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Stored result files deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Task not found."},"409":{"description":"Generation is still running."},"503":{"description":"Deletion incomplete; retry."}},"summary":"Delete stored result files and retain task history","tags":["Generations"]},"get":{"description":"Authenticated result download using existing storage, Range and deletion behavior. Until a result is stored, no media is returned.","operationId":"get_v1_generations_id_content","responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"Stored media"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Result not available"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not ready"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Download generation content","tags":["Media"]},"head":{"description":"Authenticated result download using existing storage, Range and deletion behavior. Until a result is stored, no media is returned.","operationId":"head_v1_generations_id_content","responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"Stored media"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Result not available"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not ready"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Inspect generation content","tags":["Media"]},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}]},"/v1/generations/{id}/last-frame":{"get":{"description":"Requires task ownership. Returns 404 when no archived last frame exists. Supports Range and conditional requests. Use media-access for a signed browser URL.","operationId":"get_v1_tasks_id_last_frame","responses":{"200":{"description":"Last frame image"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Download the archived video last frame","tags":["Media"],"x-required-scope":"generation"},"head":{"description":"Requires task ownership. Returns 404 when no archived last frame exists. Supports Range and conditional requests. Use media-access for a signed browser URL.","operationId":"head_v1_tasks_id_last_frame","responses":{"200":{"description":"Last frame headers"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Read archived last frame headers","tags":["Media"],"x-required-scope":"generation"},"parameters":[{"$ref":"#/components/parameters/TaskID"}]},"/v1/generations/{id}/media-access":{"get":{"description":"Returns relative, time-limited URLs for a completed archived result. Anyone holding a signed URL can access it until expires_at, including after the originating API key is revoked. Request a fresh URL after expiry.","operationId":"get_v1_tasks_id_media_access","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaAccess"}}},"description":"Signed access URLs"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Create temporary signed preview and download URLs","tags":["Media"],"x-required-scope":"generation"},"parameters":[{"$ref":"#/components/parameters/TaskID"}]},"/v1/images/edits":{"post":{"description":"Returns HTTP 202 immediately after queue admission. Poll status_url until completed/failed; download content_url with the same API key. Provider execution never runs synchronously in this request. This endpoint selects media_type=image. Multipart uploads are local-storage only, with a 32 MiB total limit. S3 returns 409 direct_upload_required; upload with /v1/references/uploads and send JSON referencing that file. Local uploads are saved to the reference library; uploaded files remain reusable even if later generation admission fails. Use image/image[] for edits, input_reference for video. options is JSON text.","operationId":"post_v1_images_edits","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}},"multipart/form-data":{"schema":{"properties":{"background":{"type":"string"},"image":{"format":"binary","type":"string"},"image[]":{"items":{"format":"binary","type":"string"},"type":"array"},"model":{"type":"string"},"options":{"description":"JSON-encoded MediaOptions","type":"string"},"output_format":{"type":"string"},"prompt":{"type":"string"},"quality":{"type":"string"},"size":{"type":"string"},"timeout_seconds":{"format":"int64","maximum":9223372036,"minimum":1,"type":"integer"}},"required":["model","prompt","image"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}},"description":"Generation accepted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Budget exceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Idempotency conflict or changed estimate"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Pricing unavailable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Create an image edit","tags":["Generations"],"x-required-scope":"generation"}},"/v1/images/generations":{"post":{"description":"Returns HTTP 202 immediately after queue admission. Poll status_url until completed/failed; download content_url with the same API key. Provider execution never runs synchronously in this request. This endpoint selects media_type=image.","operationId":"post_v1_images_generations","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}},"description":"Generation accepted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Budget exceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Idempotency conflict or changed estimate"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Pricing unavailable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Create an image generation","tags":["Generations"],"x-required-scope":"generation"}},"/v1/info":{"get":{"description":"Authenticated deployment defaults and console authentication mode (public only in local API-key development mode). Defaults may not be configured for your account; GET /v1/providers is the authoritative account catalog.","operationId":"get_v1_info","responses":{"200":{"content":{"application/json":{"example":{"auth_mode":"google","live":false,"model":"mock-video-v1","provider":"mock"},"schema":{"$ref":"#/components/schemas/ServiceInfo"}}},"description":"Service information"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Get the current default provider and model","tags":["System"]}},"/v1/invitations/accept":{"post":{"description":"Ordinary invitations grant their saved organization role (Member by default); API acceptance requires organizations:manage. Acceptance cannot override the saved role. First-owner invitations require a browser session matching the invited verified email and join as Supermanager. Owner acceptance activates the company and assigns the still-authorized provisional client manager once. Declining does not consume the link.","operationId":"post_v1_invitations_accept","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"token":{"maxLength":43,"minLength":43,"type":"string"}},"required":["token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationInvitation"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Accept invitation; preview does not consume the link","tags":["Organizations"]}},"/v1/invitations/preview":{"post":{"description":"Ordinary invitations grant their saved organization role (Member by default); API acceptance requires organizations:manage. Acceptance cannot override the saved role. First-owner invitations require a browser session matching the invited verified email and join as Supermanager. Owner acceptance activates the company and assigns the still-authorized provisional client manager once. Declining does not consume the link.","operationId":"post_v1_invitations_preview","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"token":{"maxLength":43,"minLength":43,"type":"string"}},"required":["token"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationInvitation"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Preview invitation; preview does not consume the link","tags":["Organizations"]}},"/v1/key":{"get":{"description":"Requires a Gateway API key, including generation-only keys. Returns only that key and its usage for the current UTC calendar month. Browser sessions cannot authorize this endpoint. Service credentials return null key and usage. No secret is returned.","operationId":"getCurrentAPIKey","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"key":{"oneOf":[{"$ref":"#/components/schemas/APIKey"},{"type":"null"}]},"organization":{"$ref":"#/components/schemas/Organization"},"usage":{"oneOf":[{"$ref":"#/components/schemas/APIKeyMonthlyUsage"},{"type":"null"}]}},"required":["key","usage"],"type":"object"}}},"description":"Current key and monthly usage; null usage means unavailable."},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"description":"Key or usage could not be read."}},"summary":"Read the calling key, organization and member weekly allowance","tags":["API keys"]}},"/v1/me":{"get":{"description":"Returns the account identified by a browser session or personal key. The deployment service key receives 401 because it has no personal profile.","operationId":"get_v1_me","responses":{"200":{"content":{"application/json":{"example":{"email":"developer@example.com","id":"7037b5e5-2e44-4185-a2b5-d7e459c7b16a","name":"Developer"},"schema":{"$ref":"#/components/schemas/User"}}},"description":"Current account"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Get the current account","tags":["Account"],"x-required-scope":"generation"},"patch":{"description":"Requires your browser session. API keys cannot update profiles. Contact links are optional and visible to authorized company-member viewers, including the assigned client manager. An empty contacts array removes all links; omission preserves them. Labels and links are trimmed. Custom names, contacts and report columns survive subsequent sign-ins. Report columns are shared across your report views; unavailable columns are hidden for the current role and scope.","operationId":"update_profile","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"minProperties":1,"properties":{"color_preset":{"description":"Published color theme ID. Empty follows the site default; independent of dark/light/system mode.","maxLength":64,"type":"string"},"contacts":{"$ref":"#/components/schemas/ContactLinks"},"name":{"description":"Trimmed display name without control characters.","maxLength":100,"minLength":1,"type":"string"},"report_columns":{"$ref":"#/components/schemas/ReportColumns"},"theme":{"default":"system","enum":["dark","light","system"],"type":"string"}},"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}},"description":"Updated user"},"400":{"description":"Invalid profile"},"401":{"description":"Sign-in required"},"403":{"description":"Browser session required"}},"security":[{"sessionAuth":[]}],"summary":"Update your display name, appearance, contact links or report columns","tags":["Account"]}},"/v1/models":{"get":{"description":"Only enabled models visible to this API key. Raw unique model IDs, or provider/model for ambiguous names. capabilities preserves full metadata, controls and role-filtered gateway prices.","operationId":"list_models","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OpenAIModel"},"type":"array"},"object":{"const":"list"}},"type":"object"}}},"description":"Model catalog"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"List available models","tags":["Catalog"]}},"/v1/models/{model}":{"get":{"description":"Only enabled models visible to this API key. Raw unique model IDs, or provider/model for ambiguous names. capabilities preserves full metadata, controls and role-filtered gateway prices.","operationId":"retrieve_model","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenAIModel"}}},"description":"Model catalog"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Model not available"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Retrieve a model","tags":["Catalog"]},"parameters":[{"in":"path","name":"model","required":true,"schema":{"type":"string"}}]},"/v1/organizations":{"get":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"get_v1_organizations","parameters":[{"in":"query","name":"all","schema":{"default":false,"type":"boolean"}},{"description":"Include customer spend for the period and all-time latest accepted generation. Current authorization applies; summaries are omitted for Developer and Member roles.","in":"query","name":"view","schema":{"enum":["summary"],"type":"string"}},{"description":"First included date in timezone; defaults to this month's first day. Used with view=summary.","in":"query","name":"from","schema":{"format":"date","type":"string"}},{"description":"Last included date in timezone; defaults to today. Used with view=summary.","in":"query","name":"to","schema":{"format":"date","type":"string"}},{"description":"IANA timezone for period boundaries, used with view=summary.","in":"query","name":"timezone","schema":{"default":"UTC","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"as_of":{"description":"Server reference time for view=summary.","format":"date-time","type":"string"},"data":{"items":{"$ref":"#/components/schemas/Organization"},"type":"array"}},"type":"object"}}},"description":"Success"},"400":{"dates or timezone":null,"description":"Invalid view"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"},"503":{"description":"Usage summary is unavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List memberships; administrators may set all=true","tags":["Organizations"]},"post":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"post_v1_organizations","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"admin_user":{"description":"Optional first manager: existing user email or UUID. If omitted or blank, administrators manage the organization until a manager is assigned.","type":"string"},"domain":{"description":"Required company website or domain. Unique after hostname normalization.","maxLength":2048,"minLength":1,"type":"string"},"name":{"type":"string"}},"required":["name","domain"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Company name or website already exists"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Create organization and first manager (administrator)","tags":["Organizations"]}},"/v1/organizations/{id}/request-logging":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"put":{"description":"Managers can minimize retained request content. New tasks inherit this setting when accepted. After a minimized task finishes, its prompt, instructions, input references, raw provider usage and webhook destination are removed; status, normalized usage and cost remain. In-flight tasks and existing task records keep the policy they had when accepted.","operationId":"updateOrganizationRequestLogging","requestBody":{"content":{"application/json":{"schema":{"properties":{"minimize_request_logging":{"type":"boolean"}},"required":["minimize_request_logging"],"type":"object"}}},"required":true},"responses":{"204":{"description":"Request logging setting saved"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}},"summary":"Set request logging for new organization generations","tags":["Organizations"],"x-required-scope":"organizations:manage"}},"/v1/organizations/{id}/storage":{"get":{"description":"Managers can read settings. Administrators without manager membership can only read the selected driver. Secrets are never returned. The default is Gateway storage. API keys need organizations:manage.","operationId":"getOrganizationStorage","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"can_manage":{"description":"True only for managers. Administrators without this membership receive only the selected storage driver.","type":"boolean"},"gateway_allowance_bytes":{"description":"Per-organization Gateway allowance in bytes; null means unlimited.","nullable":true,"type":"integer"},"settings":{"$ref":"#/components/schemas/StorageSettings"}},"type":"object"}}},"description":"Selected storage and free Gateway allowance"}},"summary":"Read organization storage settings","tags":["Organizations"],"x-required-scope":"organizations:manage"},"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"put":{"description":"Managers only, including administrators who also hold this membership. Use driver gateway or s3. S3 object access and browser preflights are tested before saving. Missing CORS is configured for UI_PUBLIC_URL (or API_PUBLIC_URL, then request Origin), preserving existing rules and bucket privacy. Missing CORS requires read/update rights; browser_uploads_pending indicates a confirmed policy still propagating. Keys using shared providers use this selection for new uploads and generations, using organization storage ownership. Keys using personal providers use the user’s personal storage. Existing files are not moved or deleted and retain their original connection. Blank credentials preserve the saved credentials; changing endpoints requires both credentials again.","operationId":"updateOrganizationStorage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageSettings"}}},"description":"Saved settings"}},"summary":"Select Gateway storage or organization S3","tags":["Organizations"],"x-required-scope":"organizations:manage"}},"/v1/organizations/{id}/storage/check":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"post":{"description":"Managers only, including administrators who also hold this membership. Verifies write, read and delete access using a temporary object and checks PUT/GET/HEAD browser preflights for the configured frontend origin (falling back to the request Origin). Missing browser access returns storage_browser_setup_required. Does not switch storage or change CORS.","operationId":"checkOrganizationStorage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUpdate"}}},"required":true},"responses":{"200":{"description":"Connection verified"}},"summary":"Test organization S3 without saving","tags":["Organizations"],"x-required-scope":"organizations:manage"}},"/v1/organizations/{organizationId}/model-access":{"get":{"description":"Administrator or sales browser session with effective models permission for this client. Organization Managers cannot enable hidden models themselves. Provider and key restrictions still apply.","operationId":"get_v1_organizations_organizationId_model_access","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ModelSetting"},"type":"array"},"model_ids":{"items":{"format":"uuid","type":"string"},"type":"array"},"version":{"minimum":1,"type":"integer"}},"required":["data","model_ids","version"],"type":"object"}}},"description":"Registered models, additional grants and version"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read the organization's additional model grants","tags":["Organizations"]},"parameters":[{"in":"path","name":"organizationId","required":true,"schema":{"format":"uuid","type":"string"}}],"put":{"description":"Administrator or sales browser session with effective models permission for this client. A model is available when enabled_by_default is true OR its stable model setting ID is granted to this organization. Removing a grant does not deny a globally enabled model.","operationId":"put_v1_organizations_organizationId_model_access","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationModelAccess"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationModelAccess"}}},"description":"Saved grants"},"403":{"description":"Administrator access required"},"404":{"description":"Organization or model setting does not exist"},"409":{"description":"Version changed; reload settings"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Replace the organization's additional model grants","tags":["Organizations"]}},"/v1/organizations/{org}":{"get":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"get_v1_organizations_org","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Organization balance and weekly allowance","tags":["Organizations"]},"put":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"put_v1_organizations_org","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"credit_limit_usd":{"maximum":1000000,"minimum":0,"type":"number"},"default_weekly_limit_usd":{"maximum":1000000,"minimum":0,"type":["number","null"]},"markup_percent":{"description":"Administrators only. Omit to preserve, null to inherit, zero to disable markup. Applies to new shared-provider generations.","maximum":1000,"minimum":0,"multipleOf":0.01,"type":["number","null"]},"name":{"type":"string"}},"required":["name","default_weekly_limit_usd"],"type":"object"}}},"required":true},"responses":{"204":{"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Update organization; credit limit requires administrator","tags":["Organizations"]}},"/v1/organizations/{org}/audit/events":{"get":{"description":"Current Manager, Supermanager or Administrator access to this organization is required. API keys also need organizations:manage and must belong to this organization or be personal. Events contain safe changed fields, immutable identity labels and no credentials or request content. Historical snapshots never authorize access.","operationId":"get__v1_organizations_org_audit_events","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"First included calendar date in timezone, YYYY-MM-DD. Defaults to the first day of this month.","in":"query","name":"from","schema":{"type":"string"}},{"description":"Last included calendar date. Defaults to today. The backend uses an exclusive next-day boundary.","in":"query","name":"to","schema":{"type":"string"}},{"description":"IANA timezone; defaults to UTC.","in":"query","name":"timezone","schema":{"type":"string"}},{"description":"Actor ID, email or name; case-insensitive substring for names and email.","in":"query","name":"actor_id","schema":{"type":"string"}},{"description":"Exact action identifier.","in":"query","name":"action","schema":{"type":"string"}},{"description":"Exact object type.","in":"query","name":"object_type","schema":{"type":"string"}},{"description":"Exact object or key ID.","in":"query","name":"object_id","schema":{"type":"string"}},{"description":"success, denied or failed.","in":"query","name":"outcome","schema":{"type":"string"}},{"description":"system, organization or personal.","in":"query","name":"scope","schema":{"type":"string"}},{"description":"Exact server-generated correlation ID.","in":"query","name":"correlation_id","schema":{"type":"string"}},{"description":"Exclusive event ID cursor, not an offset; defaults to zero.","in":"query","name":"before_id","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventPage"}}},"description":"Safe history. Lists contain up to 50 rows."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List management audit events","tags":["Audit"],"x-required-scope":"organizations:manage"}},"/v1/organizations/{org}/audit/events/{event}":{"get":{"description":"Current Manager, Supermanager or Administrator access to this organization is required. API keys also need organizations:manage and must belong to this organization or be personal. Events contain safe changed fields, immutable identity labels and no credentials or request content. Historical snapshots never authorize access.","operationId":"get__v1_organizations_org_audit_events_event","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"event","required":true,"schema":{"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEvent"}}},"description":"Safe history. Lists contain up to 50 rows."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Event not found in the permitted scope"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read one management audit event","tags":["Audit"],"x-required-scope":"organizations:manage"}},"/v1/organizations/{org}/audit/revoked-keys":{"get":{"description":"Current Manager, Supermanager or Administrator access to this organization is required. API keys also need organizations:manage and must belong to this organization or be personal. Events contain safe changed fields, immutable identity labels and no credentials or request content. Historical snapshots never authorize access.","operationId":"get__v1_organizations_org_audit_revoked_keys","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"First included calendar date in timezone, YYYY-MM-DD. Defaults to the first day of this month.","in":"query","name":"from","schema":{"type":"string"}},{"description":"Last included calendar date. Defaults to today. The backend uses an exclusive next-day boundary.","in":"query","name":"to","schema":{"type":"string"}},{"description":"IANA timezone; defaults to UTC.","in":"query","name":"timezone","schema":{"type":"string"}},{"description":"Actor ID, email or name; case-insensitive substring for names and email.","in":"query","name":"actor_id","schema":{"type":"string"}},{"description":"Exact object or key ID.","in":"query","name":"object_id","schema":{"type":"string"}},{"description":"Revoked-key history only; 0 to 100000.","in":"query","name":"offset","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokedKeyPage"}}},"description":"Safe history. Lists contain up to 50 rows."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List immutable revoked-key history","tags":["Audit"],"x-required-scope":"organizations:manage"}},"/v1/organizations/{org}/balance-history":{"get":{"description":"Returns manual credits, payment credits and corrections, plus attempts without a ledger entry. Requires manager, assigned client manager or administrator access; API keys require organizations:manage and matching organization binding. Test payments are visible only to administrators. Newest first, 50 entries per page.","operationId":"get_organization_balance_history","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"offset","schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/BalanceEntry"},"type":"array"},"has_more":{"type":"boolean"}},"required":["data","has_more"],"type":"object"}}},"description":"Unified history page"},"403":{"description":"Financial access or organization binding denied"}},"summary":"List unified balance activity","tags":["Payments"]}},"/v1/organizations/{org}/client-manager":{"put":{"description":"Administrators may assign or clear any company's sales employee. Lead and regional client managers using browser sessions may reassign a company only when both its current and proposed employees belong to their own branch (including themselves). Leaders cannot clear assignments or claim unassigned companies. The target must already hold a sales role. One employee can serve multiple organizations.","operationId":"put_v1_organizations_org_client_manager","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"user":{"description":"Existing client manager email or user ID; empty string clears the assignment.","type":"string"}},"required":["user"],"type":"object"}}},"required":true},"responses":{"204":{"description":"Assignment updated"},"403":{"description":"Administrator access or an eligible sales leader's own branch required"},"404":{"description":"Organization or eligible client manager not found"}},"summary":"Assign or clear the organization's client manager","tags":["Organizations"]}},"/v1/organizations/{org}/credits":{"get":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"get_v1_organizations_org_credits","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}},{"in":"query","name":"offset","schema":{"maximum":100000,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OrganizationCredit"},"type":"array"}},"type":"object"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List latest 50 credits; supports offset","tags":["Organizations"]},"post":{"description":"Administrators can apply payments, promos and corrections. Sales browser sessions require effective topup permission and current client scope; only positive payment credits without an amount ceiling are allowed, with a nonblank reason. external_id makes retries idempotent. Negative corrections, promo credits and API-key delegation are prohibited. Amounts are USD.","operationId":"post_v1_organizations_org_credits","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"amount_usd":{"multipleOf":0.000001,"type":"number"},"external_id":{"maxLength":200,"minLength":1,"type":"string"},"kind":{"enum":["payment","promo","adjustment"]},"reason":{"maxLength":1000,"type":"string"}},"required":["amount_usd","kind","external_id"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationCredit"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Apply an idempotent credit or delegated sales top-up","tags":["Organizations"]}},"/v1/organizations/{org}/generations":{"get":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"get_v1_organizations_org_tasks","parameters":[{"in":"query","name":"offset","schema":{"default":0,"maximum":1000000,"minimum":0,"type":"integer"}},{"in":"path","name":"org","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Generation"},"type":"array"}},"type":"object"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List organization tasks; members see only their own","tags":["Organizations"]}},"/v1/organizations/{org}/generations/{id}":{"get":{"description":"Organization-scoped access. Browser sessions are supported. Live membership and role checks apply: Managers see metadata only, Content Officers read all retained content, Developers and Members read their own content. Deletion requires Supermanager or ownership as Developer/Member.","operationId":"get_organization__generations_id","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}},"description":"Generation"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Generation not found"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Retrieve asynchronous generation","tags":["Generations"]}},"/v1/organizations/{org}/generations/{id}/content":{"delete":{"description":"Organization-scoped access. Browser sessions are supported. Live membership and role checks apply: Managers see metadata only, Content Officers read all retained content, Developers and Members read their own content. Deletion requires Supermanager or ownership as Developer/Member.","operationId":"delete_organization__generations_id_content","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Stored result files deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Task not found."},"409":{"description":"Generation is still running."},"503":{"description":"Deletion incomplete; retry."}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Delete stored result files and retain task history","tags":["Generations"]},"get":{"description":"Organization-scoped access. Browser sessions are supported. Live membership and role checks apply: Managers see metadata only, Content Officers read all retained content, Developers and Members read their own content. Deletion requires Supermanager or ownership as Developer/Member.","operationId":"get_organization__generations_id_content","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"Stored media"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Result not available"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not ready"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Download generation content","tags":["Media"]},"head":{"description":"Organization-scoped access. Browser sessions are supported. Live membership and role checks apply: Managers see metadata only, Content Officers read all retained content, Developers and Members read their own content. Deletion requires Supermanager or ownership as Developer/Member.","operationId":"head_organization__generations_id_content","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"Stored media"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Result not available"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not ready"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Inspect generation content","tags":["Media"]}},"/v1/organizations/{org}/generations/{id}/last-frame":{"get":{"description":"Organization-scoped access. Browser sessions are supported. Live membership and role checks apply: Managers see metadata only, Content Officers read all retained content, Developers and Members read their own content. Deletion requires Supermanager or ownership as Developer/Member.","operationId":"get_organization__generations_id_last-frame","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Last frame image"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Download the archived video last frame","tags":["Media"],"x-required-scope":"generation"},"head":{"description":"Organization-scoped access. Browser sessions are supported. Live membership and role checks apply: Managers see metadata only, Content Officers read all retained content, Developers and Members read their own content. Deletion requires Supermanager or ownership as Developer/Member.","operationId":"head_organization__generations_id_last-frame","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Last frame headers"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read archived last frame headers","tags":["Media"],"x-required-scope":"generation"}},"/v1/organizations/{org}/generations/{id}/media-access":{"get":{"description":"Organization-scoped access. Browser sessions are supported. Live membership and role checks apply: Managers see metadata only, Content Officers read all retained content, Developers and Members read their own content. Deletion requires Supermanager or ownership as Developer/Member.","operationId":"get_organization__generations_id_media-access","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaAccess"}}},"description":"Signed access URLs"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Create temporary signed preview and download URLs","tags":["Media"],"x-required-scope":"generation"}},"/v1/organizations/{org}/invitations":{"get":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"get_v1_organizations_org_invitations","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OrganizationInvitation"},"type":"array"}},"type":"object"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List latest 100 invitations","tags":["Organizations"]},"post":{"description":"The issuer must be allowed to assign the selected role: Administrator/Supermanager may assign any organization role; Manager may assign Developer or Member. Omitted role defaults to Member. Key mutations require organizations:manage; system authority additionally requires system:manage.","operationId":"post_v1_organizations_org_invitations","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"role":{"default":"member","enum":["supermanager","admin","content_officer","developer","member"],"type":"string"}},"type":"object"}}},"required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationInvitation"}}},"description":"Success"},"400":{"description":"Invalid role or request fields"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Create seven-day single-use invitation with a selected organization role","tags":["Organizations"]}},"/v1/organizations/{org}/invitations/{invite}":{"delete":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"delete_v1_organizations_org_invitations_invite","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}},{"in":"path","name":"invite","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Revoke invitation","tags":["Organizations"]}},"/v1/organizations/{org}/limits":{"get":{"description":"Administrators only. Positive integer quotas; null organization values inherit the corresponding system default. User counters combine all keys within the same organization; personal keys use a separate counter. Changes apply to subsequent requests, without resetting usage counters. Version guards concurrent edits. Accepted generations continue even if limits are lowered.","operationId":"get_organization_limits","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLimitPolicy"}}},"description":"System defaults, organization overrides and effective values"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Organization not found"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read organization request limits","tags":["System"],"x-required-scope":"system:manage"},"parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"put":{"description":"Administrators only. Positive integer quotas; null organization values inherit the corresponding system default. User counters combine all keys within the same organization; personal keys use a separate counter. Changes apply to subsequent requests, without resetting usage counters. Version guards concurrent edits. Accepted generations continue even if limits are lowered.","operationId":"put_organization_limits","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLimitConfig"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLimitPolicy"}}},"description":"System defaults, organization overrides and effective values"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Organization not found"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Replace organization request limits","tags":["System"],"x-required-scope":"system:manage"}},"/v1/organizations/{org}/markups":{"get":{"description":"Administrators or sales browser sessions with effective pricing permission for this client. The first configured rule wins in this order — company model, company provider, company default, system model, system provider, system default. Zero is an explicit override. System default must be set; company default may be null to inherit. Replacements are atomic and require the current version. Only new tasks use changed rates. Model IDs are exact and scoped to their provider; retired IDs remain valid rules.","operationId":"get_organization_markups","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkupPolicy"}}},"description":"System and organization pricing rules (authorized commercial users only)"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Organization not found"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read organization markup rules","tags":["System"],"x-required-scope":"system:manage"},"parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"put":{"description":"Administrators or sales browser sessions with effective pricing permission for this client. The first configured rule wins in this order — company model, company provider, company default, system model, system provider, system default. Zero is an explicit override. System default must be set; company default may be null to inherit. Replacements are atomic and require the current version. Only new tasks use changed rates. Model IDs are exact and scoped to their provider; retired IDs remain valid rules.","operationId":"put_organization_markups","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkupConfig"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkupPolicy"}}},"description":"System and organization pricing rules (authorized commercial users only)"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Organization not found"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Replace organization markup rules","tags":["System"],"x-required-scope":"system:manage"}},"/v1/organizations/{org}/markups/catalog":{"get":{"description":"Administrator or browser-session sales employee with pricing permission and access to this client. Does not expose provider credentials or allow global changes.","operationId":"get_organization_markup_catalog","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Provider and model picker metadata in a data array"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"Read the provider/model picker catalogue for company markup rules","tags":["Organizations"]}},"/v1/organizations/{org}/members":{"get":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"get_v1_organizations_org_members","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/OrganizationMember"},"type":"array"}},"type":"object"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List members and weekly spending","tags":["Organizations"]}},"/v1/organizations/{org}/members/{user}":{"delete":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"delete_v1_organizations_org_members_user","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}},{"in":"path","name":"user","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Remove member and revoke their organization keys","tags":["Organizations"]},"put":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"put_v1_organizations_org_members_user","parameters":[{"in":"path","name":"org","required":true,"schema":{"type":"string"}},{"in":"path","name":"user","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"role":{"enum":["member","admin"]},"weekly_limit_usd":{"description":"Omit to inherit the organization default for a new or restored member, or keep an active member's current limit. Null means unlimited; zero blocks generation.","maximum":1000000,"minimum":0,"type":["number","null"]}},"required":["role"],"type":"object"}}},"required":true},"responses":{"204":{"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Set member role and weekly limit","tags":["Organizations"]}},"/v1/organizations/{org}/payment-methods":{"get":{"description":"Manager or administrator; API keys require organizations:manage. Test methods are visible only to administrators.","operationId":"get_v1_organizations_org_payment_methods","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"currency":{"type":"string"},"data":{"items":{"additionalProperties":false,"properties":{"fee_mode":{"enum":["service","organization"],"type":"string"},"id":{"type":"string"},"kind":{"type":"string"},"live":{"type":"boolean"},"name":{"type":"string"},"stablecoin":{"$ref":"#/components/schemas/StablecoinConfig"}},"type":"object"},"type":"array"},"max_cents":{"type":"integer"},"min_cents":{"type":"integer"}},"type":"object"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"List enabled top-up methods","tags":["Payments"]}},"/v1/organizations/{org}/payments":{"get":{"description":"Manager only. Amounts are integer USD cents. credited_cents is the current net contribution after fees, refunds and disputed funds; test payments always show zero credited.","operationId":"get_v1_organizations_org_payments","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"offset","schema":{"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"data":{"items":{"$ref":"#/components/schemas/Payment"},"type":"array"},"has_more":{"type":"boolean"}},"type":"object"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"List payment history","tags":["Payments"]},"post":{"description":"Stablecoins additionally require network, token and company billing details. Card payments with stripe_invoices=false require company billing details and use the same local VAT rules; Stripe only charges the quoted gross amount, without automatic_tax or invoice_creation. VAT is calculated locally from the installation seller profile and country/registration-status rules. VAT registration must be verified for status-specific treatment. There is no Stripe dependency for stablecoins. The server reserves an exact six-decimal amount including a payment fee below one cent. Manager only. Idempotency is scoped to organization and actor. Reusing the key with a different amount, provider or fee mode returns 409. The supplied fee_mode must match the displayed current provider mode for a new payment. Redirects do not grant credit. Test payments never produce spendable credits.","operationId":"post_v1_organizations_org_payments","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"maxLength":128,"minLength":1,"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentCheckout"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"Create or resume a card or stablecoin payment","tags":["Payments"]}},"/v1/organizations/{org}/payments/{id}":{"delete":{"description":"Requires organization management access. Only pending requests can be cancelled. History and the exact amount reservation are retained permanently. Confirming and paid requests return 409.","operationId":"delete_v1_organizations_org_payments_id","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}},"description":"Cancelled payment"},"403":{"description":"Organization access denied"},"409":{"description":"Payment cannot be cancelled"}},"summary":"Cancel an unpaid stablecoin payment","tags":["Payments"]},"get":{"description":"Checks current management rights and the organization binding of the supplied API key.","operationId":"get_v1_organizations_org_payments_id","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"Read a payment","tags":["Payments"]}},"/v1/organizations/{org}/payments/{id}/checkout":{"post":{"description":"Organization manager only. Reuses an open Checkout, or renews it after Stripe confirms the old session expired. Preserves payment ID, invoice, principal and VAT. Paid payments return their settled state. Concurrent requests and lost creation responses share a durable attempt/idempotency key. The same 30-day request deadline applies to native and locally invoiced Stripe requests. No renewal is allowed after expiry. The deadline is creation plus exactly 720 hours; an expired short Stripe session leaves the request pending before that deadline.","operationId":"post_v1_organizations_org_payments_id_checkout","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}},"description":"Existing payment with current checkout URL or already-paid status"},"403":{"description":"Not an organization manager or wrong organization"},"409":{"description":"Payment cannot currently be resumed or insufficient Stripe Checkout time remains"},"410":{"description":"Payment request expired; create a new payment"},"503":{"description":"Provider unavailable; no replacement is created without verification"}},"summary":"Resume a locally invoiced Stripe payment","tags":["Payments"]}},"/v1/organizations/{org}/payments/{id}/invoice":{"get":{"description":"Organization manager only. Issues an immutable numbered PDF on the first request; retries return the same stored bytes. Available for stablecoins and card payments created with Stripe Invoices disabled. Uses the seller, logo, buyer and VAT snapshot saved with the payment. Due date is the request creation plus 30 days. Stablecoins show a fixed 1 USD = 1 selected token rate. Cancelled requests cannot issue invoices; expired requests can only redownload an already issued PDF. Stripe processor fees are not invoice items.","operationId":"get_v1_organizations_org_payments_id_invoice","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/pdf":{"schema":{"format":"binary","type":"string"}}},"description":"Private PDF attachment with Cache-Control no-store","headers":{"Content-Disposition":{"schema":{"type":"string"}}}},"403":{"description":"Not an organization manager or payment belongs to another organization"},"409":{"description":"Cancelled payment or no usable unpaid card checkout"},"503":{"description":"Payment uses native Stripe invoicing or cannot supply a document"}},"summary":"Generate or download a local invoice PDF","tags":["Payments"]}},"/v1/organizations/{org}/payments/{id}/qr":{"get":{"description":"Organization management access is required. The QR encodes the address only; the accompanying payment card specifies the token, network and exact amount.","operationId":"get_v1_organizations_org_payments_id_qr","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"image/png":{"schema":{"format":"binary","type":"string"}}},"description":"Private address QR image"},"403":{"description":"Organization access denied"},"404":{"description":"Stablecoin payment not found"}},"summary":"Read the receiving-address QR image","tags":["Payments"]}},"/v1/organizations/{org}/payments/{id}/refresh":{"post":{"description":"Fetches current provider state under a payment lock. May return 503 while actual processing fees are not yet available. Safe to retry. Refunds and disputes can reduce available balance below zero.","operationId":"post_v1_organizations_org_payments_id_refresh","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"Reconcile a payment with Stripe","tags":["Payments"]}},"/v1/organizations/{org}/references":{"get":{"description":"Organization-scoped access. Browser sessions are supported. Live membership and role checks apply: Managers see metadata only, Content Officers read all retained content, Developers and Members read their own content. Deletion requires Supermanager or ownership as Developer/Member.","operationId":"get_organization__references","parameters":[{"in":"query","name":"offset","schema":{"default":0,"maximum":1000000,"minimum":0,"type":"integer"}},{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ReferenceImage"},"type":"array"},"has_more":{"type":"boolean"},"next_offset":{"type":"integer"}},"required":["data","has_more","next_offset"],"type":"object"}}},"description":"Up to 48 files from the authenticated owner's library"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List your reference files, newest first","tags":["References"]}},"/v1/organizations/{org}/references/{id}":{"delete":{"description":"Organization-scoped access. Browser sessions are supported. Live membership and role checks apply: Managers see metadata only, Content Officers read all retained content, Developers and Members read their own content. Deletion requires Supermanager or ownership as Developer/Member.","operationId":"delete_organization__references_id","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"File deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Permanently delete a reference file","tags":["References"]}},"/v1/organizations/{org}/reports":{"get":{"description":"Organization role checks apply. Key mutations require organizations:manage; system-only operations additionally require system:manage. Amounts are USD.","operationId":"get_v1_organizations_org_reports","parameters":[{"description":"Aggregate all matching requests; ignores pagination. Cannot combine with CSV.","in":"query","name":"view","schema":{"enum":["summary"],"type":"string"}},{"description":"Summary calendar buckets in the selected timezone. Weeks start Monday. A range of one month or less has one monthly bucket. Maximum 10000 buckets.","in":"query","name":"interval","schema":{"default":"day","enum":["day","week","month"],"type":"string"}},{"description":"Exact user ID or email (case-insensitive); financial viewers only.","in":"query","name":"user","schema":{"type":"string"}},{"description":"IANA time zone for inclusive from/to calendar dates; CSV timestamps remain UTC.","in":"query","name":"timezone","schema":{"default":"UTC","type":"string"}},{"description":"Export every matching row as CSV; limit and offset are ignored.","in":"query","name":"format","schema":{"enum":["csv"],"type":"string"}},{"in":"path","name":"org","required":true,"schema":{"type":"string"}},{"in":"query","name":"from","schema":{"type":"string"}},{"in":"query","name":"to","schema":{"type":"string"}},{"in":"query","name":"api_key_id","schema":{"type":"string"}},{"description":"Exact generation ID. Combined with the other filters.","in":"query","name":"generation_id","schema":{"format":"uuid","type":"string"}},{"in":"query","name":"limit","schema":{"type":"integer"}},{"in":"query","name":"offset","schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ReportSummary"},{"properties":{"data":{"items":{"type":"object"},"type":"array"},"has_more":{"type":"boolean"}},"type":"object"}]}},"text/csv":{"example":"Created at (UTC),Cost (USD)","schema":{"type":"string"}}},"description":"Success"},"403":{"description":"Insufficient role, membership or scope"},"409":{"description":"Last supermanager, used invitation or conflicting payment ID"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Organization expense report; members see their own records","tags":["Organizations"]}},"/v1/organizations/{org}/reports/{id}":{"get":{"description":"Uses live organization membership and the same financial author scope as the Reports list. Manager and client manager receive only status and accounting; Developer and Member can read only their own reports. Returns every retained public generation field and exact saved request settings when content access is allowed. Minimal logging omits prompt, instructions, webhook and references, exposing only retained resolution, ratio, duration and generate_audio. Customer views retain the existing financial sanitization. Provider/storage credentials are never returned.","operationId":"get_v1_organizations_org_reports_id","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDetail"}}},"description":"Generation details authorized for this viewer"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No generation report in the authorized scope"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read full organization generation report","tags":["Reports"]}},"/v1/organizations/{org}/reports/{id}/content":{"get":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"get_v1_organizations_org_reports_id_content","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file content"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read organization generation result","tags":["Reports"]},"head":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"head_v1_organizations_org_reports_id_content","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file headers"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Inspect organization generation result","tags":["Reports"]}},"/v1/organizations/{org}/reports/{id}/last-frame":{"get":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"get_v1_organizations_org_reports_id_last_frame","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file content"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read organization generation last frame","tags":["Reports"]},"head":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"head_v1_organizations_org_reports_id_last_frame","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file headers"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Inspect organization generation last frame","tags":["Reports"]}},"/v1/organizations/{org}/sales-permissions":{"get":{"description":"Browser session and current organization access required. Evaluates current grants and client assignment; does not grant membership or other organization rights.","operationId":"get_organization_sales_permissions","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"models":{"type":"boolean"},"pricing":{"type":"boolean"},"topup":{"type":"boolean"}},"type":"object"}}},"description":"Current commercial permissions"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"sessionAuth":[]}],"summary":"Read the caller's commercial permissions for this client","tags":["Organizations"]}},"/v1/organizations/{org}/support":{"get":{"description":"Browser session required. Available to current company members, its assigned sales hierarchy and Administrators. Unassigned companies return a null client_manager. Only opt-in links are exposed; no login email or personal settings are returned. API keys cannot read this endpoint.","operationId":"get_organization_support","parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"client_manager":{"properties":{"contacts":{"$ref":"#/components/schemas/ContactLinks"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"picture":{"format":"uri","type":"string"}},"type":["object","null"]}},"required":["client_manager"],"type":"object"}}},"description":"Assigned client manager, if any"},"400":{"description":"Invalid company ID"},"401":{"description":"Sign-in required"},"403":{"description":"Company access or browser session required"},"503":{"description":"Support contacts unavailable"}},"security":[{"sessionAuth":[]}],"summary":"Get your company's client manager and shared contact links","tags":["Organizations"]}},"/v1/organizations/{org}/vat-verification":{"get":{"description":"Organization management access and credential organization binding are required.","operationId":"get_v1_organizations_org_vat_verification","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentVATVerification"}}},"description":"Verification or an empty version-zero record"},"403":{"description":"Organization management access required"}},"summary":"Read administrator verification of buyer VAT registration","tags":["Payments"]},"parameters":[{"in":"path","name":"org","required":true,"schema":{"format":"uuid","type":"string"}}],"put":{"description":"Administrator only. Proof is bound to exact legal name, country and VAT number. Verified records require evidence and expire after 90 days by default, with an explicit maximum of 366 days. Browser-supplied buyer status cannot grant VAT relief.","operationId":"put_v1_organizations_org_vat_verification","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentVATVerification"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentVATVerification"}}},"description":"Saved verification"},"400":{"description":"Invalid verification evidence"},"403":{"description":"Administrator access required"},"409":{"description":"Verification version changed"}},"summary":"Record or revoke manual VAT verification","tags":["Payments"]}},"/v1/payment-integrations/{id}/settlements":{"post":{"description":"Only the dedicated pay_ token issued for this integration is accepted; sessions, Gateway API keys and Stripe keys cannot grant credits. The external ID is globally unique within the integration, with immutable organization and amount. Send cumulative fee/refund/hold totals and monotonically increasing revisions. An identical revision is a no-op; stale or conflicting revisions return 409. The ledger and payment state commit atomically. Test integrations never add spendable funds.","operationId":"post_v1_payment_integrations_id_settlements","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalPaymentSettlement"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"security":[{"paymentIntegrationAuth":[]}],"summary":"Settle an externally confirmed payment","tags":["Payments"]}},"/v1/payments/webhooks/{id}":{"post":{"description":"Raw request body, maximum 256 KiB. Verify Stripe-Signature HMAC with a five-minute tolerance. Test/live and merchant identity must match. Events trigger authoritative reconciliation rather than incremental credits. Disabled Stripe providers continue settling existing payments.","operationId":"post_v1_payments_webhooks_id","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"header","name":"Stripe-Signature","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"204":{"description":"Verified and processed or safely ignored"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"security":[],"summary":"Receive signed Stripe events","tags":["Payments"]}},"/v1/providers":{"get":{"description":"Enabled, configured providers with their available models and capability flags. Use this catalog before constructing generation requests. The mock provider produces fixed test assets without paid inference.","operationId":"get_v1_providers","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ProviderDescriptor"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"Provider and model catalog"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"List enabled and configured generation providers","tags":["Catalog"],"x-required-scope":"generation"}},"/v1/references":{"get":{"description":"Requires the generation scope when using a personal API key.","operationId":"get_v1_references","parameters":[{"in":"query","name":"offset","schema":{"default":0,"maximum":1000000,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ReferenceImage"},"type":"array"},"has_more":{"type":"boolean"},"next_offset":{"type":"integer"}},"required":["data","has_more","next_offset"],"type":"object"}}},"description":"Up to 48 files from the authenticated owner's library"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"List your reference files, newest first","tags":["References"]},"post":{"description":"Local storage only; S3 returns 409 direct_upload_required before reading the body. Use POST /v1/references/uploads for S3. Saves a PNG, JPEG, WebP or GIF (30 MiB), MP4, MOV or WebM (200 MiB), or MP3, WAV, OGG or FLAC (50 MiB) in the organization's selected local storage, under \u003corganization-id\u003e/references/. Non-administrators must use shared storage or personal S3 storage. Requires generation scope. Uploading does not create a generation task. The server detects the media type from the uploaded bytes. Identical content (SHA-256) is reused within the same organization, regardless of uploader or filename. Returns 200 and duplicate=true for an existing file; no additional file is saved.","operationId":"post_v1_references","requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"format":"binary","type":"string"}},"required":["file"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceImage"}}},"description":"Identical file already exists; the existing file is returned with duplicate=true"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceImage"}}},"description":"File saved in the reusable library"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"S3 requires direct upload; use POST /v1/references/uploads"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Upload one reference file to local storage","tags":["References"]}},"/v1/references/providers/{provider}/assets":{"get":{"description":"Requires generation scope and current content permissions; Developers and Members are restricted to their own bindings.","operationId":"list_workspace_provider_assets","parameters":[{"in":"query","name":"offset","schema":{"default":0,"maximum":1000000,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderAssetBindings"}}},"description":"Workspace assets"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Library not configured","or asset in use/shared.":null,"registration unresolved":null},"502":{"description":"Provider asset operation failed; an uncertain registration must not be repeated blindly."}},"summary":"List and refresh workspace asset bindings","tags":["References"]},"parameters":[{"description":"Selected provider connection ID.","in":"path","name":"provider","required":true,"schema":{"type":"string"}}],"post":{"description":"Requires write content access. The original remains in My storage and cannot be deleted during ingestion. Uses a signed HTTPS URL; never accepts arbitrary external URLs. Duplicate source registrations reuse their durable binding. A 202 response is preparation state, not proof of readiness. Wait for Active before using uri. Uncertain creates are reconciled without automatic resubmission.","operationId":"register_provider_asset","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"group_id":{"type":"string"},"reference_id":{"format":"uuid","type":"string"}},"required":["reference_id","group_id"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderAssetBinding"}}},"description":"Registration state"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Library not configured","or asset in use/shared.":null,"registration unresolved":null},"502":{"description":"Provider asset operation failed; an uncertain registration must not be repeated blindly."}},"summary":"Register a Gateway reference with the selected provider","tags":["References"]}},"/v1/references/providers/{provider}/assets/{id}":{"delete":{"description":"Requires write content access. Without detach, permanently deletes from BytePlus after checking queued/running tasks and other workspace bindings. The My storage original is retained. Pending/unknown registrations cannot be detached. Failures preserve retryable state; deletion markers block new task admission.","operationId":"delete_workspace_provider_asset","parameters":[{"description":"Remove only this workspace binding; retain the remote asset.","in":"query","name":"detach","schema":{"enum":["1"],"type":"string"}}],"responses":{"204":{"description":"Asset deleted or workspace binding removed"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Library not configured","or asset in use/shared.":null,"registration unresolved":null},"502":{"description":"Provider asset operation failed; an uncertain registration must not be repeated blindly."}},"summary":"Delete a remote asset or detach its workspace binding","tags":["References"]},"get":{"operationId":"get_workspace_provider_asset","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderAssetBinding"}}},"description":"Asset binding"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Library not configured","or asset in use/shared.":null,"registration unresolved":null},"502":{"description":"Provider asset operation failed; an uncertain registration must not be repeated blindly."}},"summary":"Refresh one workspace asset binding","tags":["References"]},"parameters":[{"description":"Selected provider connection ID.","in":"path","name":"provider","required":true,"schema":{"type":"string"}},{"description":"Gateway binding UUID, not the remote asset ID.","in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}]},"/v1/references/providers/{provider}/groups":{"get":{"description":"Requires generation scope and content access. Remote inventory needs ownership of the personal provider or system administration; generation-only keys need a matching administrator browser session.","operationId":"list_provider_asset_groups","parameters":[{"description":"List remote account groups instead of workspace bindings.","in":"query","name":"inventory","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderAssetGroups"}}},"description":"Groups and inventory permission"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Library not configured","or asset in use/shared.":null,"registration unresolved":null},"502":{"description":"Provider asset operation failed; an uncertain registration must not be repeated blindly."}},"summary":"List workspace or authorized remote asset groups","tags":["References"]},"parameters":[{"description":"Selected provider connection ID.","in":"path","name":"provider","required":true,"schema":{"type":"string"}}],"post":{"operationId":"create_provider_asset_group","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"name":{"maxLength":64,"minLength":1,"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderAssetGroup"}}},"description":"Group created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Library not configured","or asset in use/shared.":null,"registration unresolved":null},"502":{"description":"Provider asset operation failed; an uncertain registration must not be repeated blindly."}},"summary":"Create and bind a virtual portrait group","tags":["References"]}},"/v1/references/providers/{provider}/import":{"parameters":[{"description":"Selected provider connection ID.","in":"path","name":"provider","required":true,"schema":{"type":"string"}}],"post":{"description":"Same permissions as remote inventory; verifies that the asset belongs to an AIGC group in the configured project. Repeated imports reuse the binding.","operationId":"import_provider_asset","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"asset_id":{"type":"string"}},"required":["asset_id"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderAssetBinding"}}},"description":"Imported binding"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Library not configured","or asset in use/shared.":null,"registration unresolved":null},"502":{"description":"Provider asset operation failed; an uncertain registration must not be repeated blindly."}},"summary":"Bind an existing remote asset to the workspace","tags":["References"]}},"/v1/references/providers/{provider}/inventory":{"get":{"description":"Requires personal provider ownership or system administration. Results are provider assets, not workspace bindings. This does not grant other organizations access.","operationId":"list_remote_provider_assets","parameters":[{"in":"query","name":"group","schema":{"type":"string"}},{"description":"Unmodified continuation token from the preceding page.","in":"query","name":"next","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderAssetInventory"}}},"description":"Remote assets"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"Library not configured","or asset in use/shared.":null,"registration unresolved":null},"502":{"description":"Provider asset operation failed; an uncertain registration must not be repeated blindly."}},"summary":"Browse authorized remote account inventory","tags":["References"]},"parameters":[{"description":"Selected provider connection ID.","in":"path","name":"provider","required":true,"schema":{"type":"string"}}]},"/v1/references/uploads":{"post":{"description":"Requires generation scope. Send metadata only. For S3, returns a signed PUT target for a single multipart part. Presigned URL targets expire after 15 minutes; B2 uses timestamped SigV4 upload headers. Upload the exact file bytes with the returned headers directly to that URL, without Gateway credentials, then call the completion endpoint within 30 minutes. The SHA-256 must be the lowercase hexadecimal hash of the entire file. S3 verifies it. Maximum sizes are 30 MiB for images, 200 MiB for video and 50 MiB for audio. A duplicate returns mode=existing and reference. Local storage returns mode=local; only in this mode use POST /v1/references with multipart/form-data. Browser transfers require bucket CORS for the frontend origin and PUT/GET/HEAD; saving the storage connection configures missing access automatically when the key has CORS management rights. B2 targets use payload-signed Authorization and x-amz-date headers; send all target headers. CORS must explicitly allow Authorization for B2.","operationId":"post_v1_references_uploads","requestBody":{"content":{"application/json":{"schema":{"properties":{"content_type":{"example":"image/png","type":"string"},"name":{"type":"string"},"sha256":{"pattern":"^[0-9a-f]{64}$","type":"string"},"size_bytes":{"maximum":209715200,"minimum":1,"type":"integer"}},"required":["name","content_type","size_bytes","sha256"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Existing file; mode=existing and reference contains its library entry"},"201":{"content":{"application/json":{"schema":{"properties":{"id":{"format":"uuid","type":"string"},"mode":{"enum":["s3","local"],"type":"string"},"target":{"properties":{"headers":{"additionalProperties":{"type":"string"},"type":"object"},"url":{"format":"uri","type":"string"}},"type":"object"}},"type":"object"}}},"description":"Upload prepared"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Prepare a direct reference upload","tags":["References"]}},"/v1/references/uploads/{id}/complete":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"post":{"description":"Requires the same owner and generation scope as preparation. Exchanges only S3 metadata, verifies the single part size and pinned ETag after storage has validated the signed SHA-256 payload header, consumes the multipart upload ID and adds the file to the library. Retry this endpoint if the response is lost; successful completions return the same file while the upload receipt remains available (at least 90 minutes from preparation). No file body is sent. Failed or abandoned uploads are reclaimed by the worker after expiry.","operationId":"post_v1_references_uploads_id_complete","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceImage"}}},"description":"Saved reference or existing duplicate"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"description":"Upload expired; prepare a new upload"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Verify and finish a direct reference upload","tags":["References"]}},"/v1/references/{id}":{"delete":{"description":"Deletes the physical file from its original storage and removes its library entry. Pending generations using its URL may fail. Provider registrations still ingesting this source block deletion with 409. Requires generation scope and current write content permissions; Developers and Members can delete their own files, Supermanagers can delete workspace files, and other organizations receive 404. Storage failures preserve metadata for a retry.","operationId":"delete_v1_references_id","responses":{"204":{"description":"File deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Permanently delete a reference file","tags":["References"]},"parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}]},"/v1/sales/bonuses":{"get":{"description":"Browser sessions only. Administrators see all sales employees and former employees with ledger entries. Sales employees see themselves and current descendants. Balances include immutable accruals, corrections and recorded payouts; negative balances are allowed.","operationId":"get_sales_bonuses","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"actor_id":{"format":"uuid","type":"string"},"administrator":{"type":"boolean"},"people":{"items":{"properties":{"accrued_usd":{"type":"number"},"balance_usd":{"type":"number"},"can_pay":{"type":"boolean"},"email":{"type":"string"},"id":{"format":"uuid","type":"string"},"name":{"type":"string"},"paid_usd":{"type":"number"},"picture":{"format":"uri","type":"string"},"role":{"type":"string"}},"type":"object"},"type":"array"},"settings":{"$ref":"#/components/schemas/BonusSettings"}},"type":"object"}}},"description":"Scoped balances and global rates"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"sessionAuth":[]}],"summary":"Read USD bonus balances for self and descendants","tags":["Organizations"]}},"/v1/sales/bonuses/{employee}/entries":{"get":{"operationId":"get_sales_bonus_entries","parameters":[{"in":"path","name":"employee","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"offset","schema":{"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/BonusEntry"},"type":"array"},"has_more":{"type":"boolean"}},"type":"object"}}},"description":"Up to 50 latest entries, newest first"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"sessionAuth":[]}],"summary":"Read immutable bonus history","tags":["Organizations"]}},"/v1/sales/bonuses/{employee}/payouts":{"post":{"description":"Browser administrator or ancestor with effective bonuses permission. Self-payments are forbidden. A positive amount is subtracted from the balance, which may become negative. This records a payment without sending money. The external ID makes retries idempotent per actor; changed content conflicts. Every payment is audited.","operationId":"post_sales_bonus_payout","parameters":[{"in":"path","name":"employee","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"amount_usd":{"exclusiveMinimum":0,"type":"number"},"external_id":{"format":"uuid","type":"string"},"method":{"maxLength":200,"minLength":1,"type":"string"},"paid_at":{"format":"date","type":"string"},"reason":{"maxLength":1000,"type":"string"}},"required":["amount_usd","paid_at","method","external_id"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"id":{"format":"int64","type":"integer"}},"type":"object"}}},"description":"Recorded or existing payment ID"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Same operation ID with different payment details"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"sessionAuth":[]}],"summary":"Record an already completed bonus payment","tags":["Organizations"]}},"/v1/sales/permissions":{"get":{"description":"Browser sessions only. Administrators see all sales employees; sales employees see themselves and descendants. Includes the current shared hierarchy/permission version and grant issuer/time. No permissions are granted by default.","operationId":"get_sales_permissions","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"actor_id":{"format":"uuid","type":"string"},"administrator":{"type":"boolean"},"grants":{"items":{"$ref":"#/components/schemas/SalesGrant"},"type":"array"},"members":{"items":{"$ref":"#/components/schemas/SalesMember"},"type":"array"},"version":{"minimum":1,"type":"integer"}},"required":["version","actor_id","administrator","members","grants"],"type":"object"}}},"description":"Effective grants and scoped employee directory"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"sessionAuth":[]}],"summary":"Read effective sales permissions for self and team","tags":["Organizations"]}},"/v1/sales/permissions/{employee}/{permission}":{"put":{"description":"Browser sessions only. An administrator may grant to any sales employee. A supervisor may grant only their own effective permissions to descendants. Any ancestor may revoke. Self-grants are forbidden. Replacing or revoking a grant permanently revokes its dependent delegations. A shared version prevents stale edits. All changes are audited.","operationId":"put_sales_permission","parameters":[{"in":"path","name":"employee","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"permission","required":true,"schema":{"enum":["pricing","models","topup","bonuses"],"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"version":{"minimum":1,"type":"integer"}},"required":["enabled","version"],"type":"object"}}},"required":true},"responses":{"204":{"description":"Saved"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Permissions or hierarchy changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"sessionAuth":[]}],"summary":"Grant, replace or revoke a sales permission","tags":["Organizations"]}},"/v1/sales/team":{"get":{"description":"Lead/regional client manager browser session only. Returns the caller and their direct/indirect sales reports. Ordinary client managers and API keys are rejected.","operationId":"get__v1_sales_team","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SalesMember"},"type":"array"}},"type":"object"}}},"description":"Authorized employees only"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"sessionAuth":[]}],"summary":"Read a sales leader's own reassignment roster","tags":["Organizations"]}},"/v1/storage/usage":{"get":{"description":"Requires a generation key. Counts currently stored shared files across all keys and all time. Applies is false for keys using personal storage. Exceeded means used_bytes is strictly greater than limit_bytes; null limit means unlimited.","operationId":"getStorageUsage","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"applies":{"type":"boolean"},"exceeded":{"type":"boolean"},"limit_bytes":{"format":"int64","type":["integer","null"]},"unknown_objects":{"description":"Legacy files whose sizes are being verified.","type":"integer"},"used_bytes":{"format":"int64","type":"integer"}},"type":"object"}}},"description":"Shared storage usage"},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Read the caller's current shared-storage usage","tags":["Storage"]}},"/v1/system/billing":{"get":{"description":"Administrator only; API keys require system management access. No seller country or VAT rate is preset.","operationId":"get_v1_system_billing","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentVATSettings"}}},"description":"Versioned installation billing policy"},"403":{"description":"Administrator access required"}},"summary":"Read installation seller company and VAT rules","tags":["Payments"]},"put":{"description":"Administrator only. Maximum request body is 1 MiB, including an optional embedded invoice logo. Rules are explicit, versioned and audited. Missing cases do not default to zero VAT. Existing payment snapshots remain immutable.","operationId":"put_v1_system_billing","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentVATSettings"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentVATSettings"}}},"description":"Saved policy"},"400":{"description":"Invalid company or VAT rules"},"403":{"description":"Administrator access required"},"409":{"description":"Policy version changed"}},"summary":"Save installation seller company and VAT rules","tags":["Payments"]}},"/v1/system/branding":{"get":{"description":"Requires an administrator role. Uses an independent appearance version.","operationId":"get_site_branding","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"colors":{"items":{"properties":{"group":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"}},"type":"object"},"type":"array"},"defaults":{"$ref":"#/components/schemas/SiteBranding"},"settings":{"$ref":"#/components/schemas/SiteBranding"}},"type":"object"}}},"description":"Appearance editor data"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read installation appearance, defaults and color catalog","tags":["System"],"x-required-scope":"system:manage"},"put":{"description":"Requires an administrator role. Send complete settings and their current version. Assets are base64 PNG, JPEG or passive SVG up to 512 KiB each; email_logo and touch_icon require PNG or JPEG. Omit an asset to remove that override. Request limit 6 MiB. Changes are atomic and audited.","operationId":"put_site_branding","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBranding"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBranding"}}},"description":"Saved appearance with incremented version"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Another administrator saved a newer appearance version"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Replace installation appearance","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/catalog/documents/{hash}":{"get":{"description":"Requires a current system Administrator role. Responses use Cache-Control: no-store. See docs/catalog-sync.md for publication and warning semantics.","operationId":"get_v1_system_catalog_documents_hash","parameters":[{"in":"path","name":"hash","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"hash":{"type":"string"},"text":{"type":"string"}},"type":"object"}}},"description":"Catalogue synchronization result"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Administrator role or scope required"},"503":{"description":"Catalogue synchronization unavailable"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"Read stored catalogue source evidence","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/catalog/providers/{id}":{"get":{"description":"Requires a current system Administrator role. Responses use Cache-Control: no-store. See docs/catalog-sync.md for publication and warning semantics.","operationId":"get_v1_system_catalog_providers_id","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogState"}}},"description":"Catalogue synchronization result"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Administrator role or scope required"},"503":{"description":"Catalogue synchronization unavailable"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"Read current catalogue and unresolved warnings","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/catalog/providers/{id}/versions":{"get":{"description":"Requires a current system Administrator role. Responses use Cache-Control: no-store. See docs/catalog-sync.md for publication and warning semantics.","operationId":"get_v1_system_catalog_providers_id_versions","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CatalogState"},"type":"array"},"has_more":{"type":"boolean"}},"required":["data","has_more"],"type":"object"}}},"description":"Catalogue synchronization result"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Administrator role or scope required"},"503":{"description":"Catalogue synchronization unavailable"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"List immutable published catalogue versions","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/catalog/runs":{"get":{"description":"Requires a current system Administrator role. Responses use Cache-Control: no-store. See docs/catalog-sync.md for publication and warning semantics.","operationId":"get_v1_system_catalog_runs","parameters":[{"in":"query","name":"provider","required":false,"schema":{"type":"string"}},{"in":"query","name":"offset","required":false,"schema":{"default":0,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CatalogRun"},"type":"array"},"has_more":{"type":"boolean"}},"required":["data","has_more"],"type":"object"}}},"description":"Catalogue synchronization result"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Administrator role or scope required"},"503":{"description":"Catalogue synchronization unavailable"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"List catalogue checks including unchanged checks","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/catalog/schedules":{"get":{"description":"Requires a current system Administrator role. Responses use Cache-Control: no-store. See docs/catalog-sync.md for publication and warning semantics.","operationId":"get_v1_system_catalog_schedules","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/CatalogSchedule"},"type":"array"}},"type":"object"}}},"description":"Catalogue synchronization result"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Administrator role or scope required"},"503":{"description":"Catalogue synchronization unavailable"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"List per-provider catalogue schedules","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/catalog/schedules/{id}":{"put":{"description":"Requires a current system Administrator role. Responses use Cache-Control: no-store. See docs/catalog-sync.md for publication and warning semantics.","operationId":"put_v1_system_catalog_schedules_id","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSchedule"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSchedule"}}},"description":"Catalogue synchronization result"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Administrator role or scope required"},"409":{"description":"Version changed. Reload before saving."},"503":{"description":"Catalogue synchronization unavailable"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"Update provider daily time and sources","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/catalog/schedules/{id}/check":{"post":{"description":"Requires a current system Administrator role. Responses use Cache-Control: no-store. See docs/catalog-sync.md for publication and warning semantics.","operationId":"post_v1_system_catalog_schedules_id_check","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"queued":{"type":"boolean"}},"type":"object"}}},"description":"Catalogue synchronization result"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Administrator role or scope required"},"503":{"description":"Catalogue synchronization unavailable"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"Queue a provider catalogue check","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/catalog/settings":{"get":{"description":"Requires a current system Administrator role. Responses use Cache-Control: no-store. See docs/catalog-sync.md for publication and warning semantics.","operationId":"get_v1_system_catalog_settings","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSyncSettings"}}},"description":"Catalogue synchronization result"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Administrator role or scope required"},"503":{"description":"Catalogue synchronization unavailable"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"Read catalogue timezone and report recipient","tags":["System"],"x-required-scope":"system:manage"},"put":{"description":"Requires a current system Administrator role. Responses use Cache-Control: no-store. See docs/catalog-sync.md for publication and warning semantics.","operationId":"put_v1_system_catalog_settings","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSyncSettings"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogSyncSettings"}}},"description":"Catalogue synchronization result"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Administrator role or scope required"},"409":{"description":"Version changed. Reload before saving."},"503":{"description":"Catalogue synchronization unavailable"}},"security":[{"sessionAuth":[]},{"bearerAuth":[]}],"summary":"Update common catalogue settings","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/email":{"get":{"description":"Requires a current administrator. Returns available mail providers and saved sender settings; never returns the API key or its ciphertext.","operationId":"get_v1_system_email","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDeliverySettings"}}},"description":"Email delivery settings"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"sessionAuth":[]}],"summary":"Read email delivery provider settings","tags":["System"],"x-required-scope":"system:manage"},"put":{"description":"Requires a current system administrator. Resend requires an API key and a sender address on a verified domain. An omitted or empty api_key keeps the saved key. An empty provider removes the connection and key. Changes apply immediately without restart. Saving validates the input format; it does not send a test email or verify the key with Resend. Audited without secrets. Version prevents overwriting another administrator's edit.","operationId":"put_v1_system_email","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"api_key":{"maxLength":512,"type":"string","writeOnly":true},"from":{"example":"Sociaro \u003clogin@example.com\u003e","maxLength":320,"type":"string"},"provider":{"enum":["","resend"],"type":"string"},"version":{"format":"int64","minimum":1,"type":"integer"}},"required":["provider","from","version"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDeliverySettings"}}},"description":"Saved settings"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"apiKeyAuth":[]},{"sessionAuth":[]}],"summary":"Configure or remove an email delivery provider","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/limits":{"get":{"description":"Administrators only. Positive integer quotas; null organization values inherit the corresponding system default. User counters combine all keys within the same organization; personal keys use a separate counter. Changes apply to subsequent requests, without resetting usage counters. Version guards concurrent edits. Accepted generations continue even if limits are lowered.","operationId":"get_system_limits","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLimitPolicy"}}},"description":"System defaults, organization overrides and effective values"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Organization not found"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read system request limits","tags":["System"],"x-required-scope":"system:manage"},"put":{"description":"Administrators only. Positive integer quotas; null organization values inherit the corresponding system default. User counters combine all keys within the same organization; personal keys use a separate counter. Changes apply to subsequent requests, without resetting usage counters. Version guards concurrent edits. Accepted generations continue even if limits are lowered.","operationId":"put_system_limits","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLimitConfig"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLimitPolicy"}}},"description":"System defaults, organization overrides and effective values"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Organization not found"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Replace system request limits","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/login-providers":{"get":{"operationId":"get_v1_system_login_providers","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"available_providers":{"items":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"},"data":{"items":{"$ref":"#/components/schemas/LoginProvider"},"type":"array"},"email_delivery_configured":{"type":"boolean"}},"type":"object"}}},"description":"Provider cards, supported methods and email delivery readiness; secrets are never returned"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List login providers and available methods","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/login-providers/{provider}":{"parameters":[{"in":"path","name":"provider","required":true,"schema":{"enum":["google","email"],"type":"string"}}],"put":{"description":"Administrator only. Updates apply to new authentication attempts immediately; existing users and sessions are preserved. Google credentials are encrypted. An omitted Client Secret preserves the saved secret. Email needs configured delivery to appear on the login screen. Each provider has an independent version.","operationId":"put_v1_system_login_providers_provider","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"client_id":{"description":"Google web OAuth Client ID","maxLength":512,"type":"string"},"client_secret":{"description":"Google OAuth secret; omitted or empty preserves the saved value","maxLength":512,"type":"string","writeOnly":true},"enabled":{"type":"boolean"},"version":{"minimum":1,"type":"integer"}},"required":["enabled","version"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginProvider"}}},"description":"Saved provider without its secret"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Configure or enable a login provider","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/markups":{"get":{"description":"Administrators only. The first configured rule wins in this order — company model, company provider, company default, system model, system provider, system default. Zero is an explicit override. System default must be set; company default may be null to inherit. Replacements are atomic and require the current version. Only new tasks use changed rates. Model IDs are exact and scoped to their provider; retired IDs remain valid rules.","operationId":"get_system_markups","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkupPolicy"}}},"description":"System and organization pricing rules (administrators only)"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Organization not found"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read system markup rules","tags":["System"],"x-required-scope":"system:manage"},"put":{"description":"Administrators only. The first configured rule wins in this order — company model, company provider, company default, system model, system provider, system default. Zero is an explicit override. System default must be set; company default may be null to inherit. Replacements are atomic and require the current version. Only new tasks use changed rates. Model IDs are exact and scoped to their provider; retired IDs remain valid rules.","operationId":"put_system_markups","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkupConfig"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkupPolicy"}}},"description":"System and organization pricing rules (administrators only)"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Organization not found"},"409":{"description":"Settings changed; reload before saving"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Replace system markup rules","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/markups/catalog":{"get":{"description":"Administrators only. Lists supported paid providers and model identifiers available through shared connections. Existing rules remain editable when a model is no longer listed. Includes model capabilities, published release dates and public names for the shared model picker. No credentials are included.","operationId":"get_markup_catalog","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"icon_monochrome":{"type":"boolean"},"icon_url":{"description":"Content-versioned module artwork URL","type":"string"},"id":{"type":"string"},"models":{"items":{"allOf":[{"$ref":"#/components/schemas/MediaModel"},{"properties":{"name":{"type":"string"}},"type":"object"}]},"type":"array"},"name":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"Provider and model choices"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List providers and models for markup exceptions","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/model-settings":{"get":{"description":"Administrator only. Discovers shared provider models, including hidden models. Newly discovered models are enabled by default.","operationId":"get_v1_system_model_settings","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ModelSetting"},"type":"array"}},"type":"object"}}},"description":"Registered models"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List public model identities and default availability","tags":["System"]}},"/v1/system/model-settings/{modelId}":{"parameters":[{"in":"path","name":"modelId","required":true,"schema":{"format":"uuid","type":"string"}}],"put":{"description":"Administrator only. Public IDs are unique and case-sensitive; the previous name is not retained as an alias. Changes affect new requests; accepted generations retain their public-name snapshot.","operationId":"put_v1_system_model_settings_modelId","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"enabled_by_default":{"type":"boolean"},"public_id":{"maxLength":200,"minLength":1,"type":"string"},"version":{"minimum":1,"type":"integer"}},"required":["public_id","enabled_by_default","version"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelSetting"}}},"description":"Saved model settings"},"400":{"description":"Invalid public ID or missing fields"},"403":{"description":"Administrator access required"},"409":{"description":"Name already in use or version changed; reload settings"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Rename a model or change its default availability","tags":["System"]}},"/v1/system/payment-integrations":{"post":{"description":"Administrator only. Returns a pay_ bearer token once; only its hash is stored. This trusted issuer can settle any organization, but has no user or general system access. Integrations use service-paid fees; Stripe fee modes are configured separately.","operationId":"post_v1_system_payment_integrations","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"live":{"type":"boolean"},"name":{"maxLength":100,"type":"string"}},"required":["name","live"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"provider":{"$ref":"#/components/schemas/PaymentProvider"},"token":{"type":"string"}},"type":"object"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"Issue a trusted external payment integration credential","tags":["Payments"]}},"/v1/system/payment-notifications":{"get":{"description":"Requires an administrator and system:manage scope for API keys.","operationId":"get_v1_system_payment_notifications","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationSettings"}}},"description":"Current subscriptions and delivery queue status"},"403":{"description":"Administrator access required"}},"summary":"Get global payment email notification settings and delivery status","tags":["Payments"]},"put":{"description":"Applies to every payment provider. Both lists must be supplied. Emails must belong to existing administrators. Empty lists disable notifications. Requires administrator access and system:manage scope for API keys.","operationId":"put_v1_system_payment_notifications","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentNotificationSettings"}}},"description":"Saved subscriptions and delivery queue status"},"400":{"description":"Invalid lists or recipients are not existing administrators"},"403":{"description":"Administrator access required"},"409":{"description":"Settings version changed; reload before saving"}},"summary":"Update global payment notification recipients","tags":["Payments"]}},"/v1/system/payment-providers":{"get":{"description":"Administrator and system:manage when using an API key. Secrets are never returned.","operationId":"get_v1_system_payment_providers","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"available_providers":{"items":{"additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"},"data":{"items":{"$ref":"#/components/schemas/PaymentProvider"},"type":"array"},"stablecoin_networks":{"items":{"description":"Built-in network and accepted token contracts","type":"object"},"type":"array"}},"type":"object"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"List payment providers","tags":["Payments"]},"post":{"description":"Save disabled with a secret API key first, configure the returned webhook URL in Stripe, then update with its signing secret and enabled=true. Account and test/live mode are verified with Stripe and cannot later be changed. AUTH_PUBLIC_URL must be a public HTTPS origin.","operationId":"post_v1_system_payment_providers","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProviderUpdate"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProvider"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"Configure card or stablecoin payments","tags":["Payments"]}},"/v1/system/payment-providers/{id}":{"put":{"description":"Administrator only. Blank or omitted secrets preserve saved values. version is required for optimistic concurrency. fee_mode applies to new payments; existing payments retain their snapshot.","operationId":"put_v1_system_payment_providers_id","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProviderUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProvider"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"Update payment configuration","tags":["Payments"]}},"/v1/system/payment-providers/{id}/check":{"post":{"description":"Checks merchant identity, test/live mode and charges_enabled without charging a card or verifying webhook delivery.","operationId":"post_v1_system_payment_providers_id_check","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"account_id":{"type":"string"},"charges_enabled":{"type":"boolean"},"live":{"type":"boolean"}},"type":"object"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"Verify Stripe credentials","tags":["Payments"]}},"/v1/system/payment-providers/{id}/disable":{"post":{"description":"Stops new checkouts or external settlements. Existing Stripe payments are still reconciled, including refunds and disputes. History and encrypted Stripe credentials are retained.","operationId":"post_v1_system_payment_providers_id_disable","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"version":{"type":"integer"}},"required":["version"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentProvider"}}},"description":"Success"},"400":{"description":"Invalid request"},"403":{"description":"Role, scope, tenant or integration credential denied"},"409":{"description":"Version, idempotency, immutable payment data or fee mode conflict"},"503":{"description":"Payment verification is not available; retry the same operation"}},"summary":"Disable a payment provider or revoke an integration","tags":["Payments"]}},"/v1/system/providers":{"get":{"description":" Requires system:manage on personal keys, or a console session. Available when provider administration is configured.","operationId":"get_v1_system_providers","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AdminProvider"},"type":"array"}},"required":["data"],"type":"object"}}},"description":"Administrative provider catalog"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Shared — List every supported provider and its administrative state","tags":["Providers admin"],"x-required-scope":"system:manage","x-system-administrator-required":true},"post":{"description":"Requires a system administrator. Creates a disabled connection without testing credentials or making a paid request.","operationId":"post_v1_system_providers","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"api_type":{"type":"string"},"name":{"maxLength":120,"type":"string"}},"required":["api_type","name"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminProvider"}}},"description":"Created provider connection"},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Create an independent provider connection","tags":["Providers admin"],"x-required-scope":"system:manage"}},"/v1/system/providers/types":{"get":{"description":"Requires a system administrator. Templates describe supported serialization formats; they do not imply access or pricing for manually added models.","operationId":"get_v1_system_providers_types","responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"properties":{"fields":{"items":{"$ref":"#/components/schemas/ProviderField"},"type":"array"},"icon_monochrome":{"type":"boolean"},"icon_url":{"description":"Content-versioned module artwork URL","type":"string"},"id":{"type":"string"},"name":{"type":"string"},"profiles":{"items":{"additionalProperties":true,"type":"object"},"type":"array"}},"type":"object"},"type":"array"}},"type":"object"}}},"description":"API types with connection fields and model capability templates"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"List supported API adapters and request profile templates","tags":["Providers admin"],"x-required-scope":"system:manage"}},"/v1/system/providers/{providerId}":{"get":{"description":" Requires system:manage on personal keys, or a console session. Available when provider administration is configured.","operationId":"get_v1_system_providers_providerId","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminProvider"}}},"description":"Provider state"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Shared — Get provider configuration and live status","tags":["Providers admin"],"x-required-scope":"system:manage"},"parameters":[{"$ref":"#/components/parameters/ProviderID"}],"put":{"description":"Omitted credential fields preserve the stored value; empty strings clear it. Clearing a required credential disables the provider. Requires system:manage on personal keys, or a console session. Available when provider administration is configured.","operationId":"put_v1_system_providers_providerId","requestBody":{"content":{"application/json":{"example":{"api_key":"YOUR_PROVIDER_API_KEY","enabled":true},"schema":{"$ref":"#/components/schemas/ProviderUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminProvider"}}},"description":"Updated and validated provider state"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Shared — Update credentials, endpoints, or enabled state","tags":["Providers admin"],"x-required-scope":"system:manage"}},"/v1/system/providers/{providerId}/check":{"parameters":[{"$ref":"#/components/parameters/ProviderID"}],"post":{"description":" Requires system:manage on personal keys, or a console session. Available when provider administration is configured.","operationId":"post_v1_system_providers_providerId_check","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminProvider"}}},"description":"Refreshed provider state"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Shared — Refresh provider model and connection status information","tags":["Providers admin"],"x-required-scope":"system:manage"}},"/v1/system/reports":{"get":{"description":"Administrator financial history across all organizations and provider modes, including revoked keys. Reports distinguish expected_usd (estimate), metered_usd (reported consumption), and tariff_usd (bill-confirmed gross price). actual_usd is the separate cash payment. Generation cost consumes organization balance and member weekly allowance regardless of package coverage. Provider charge and package units remain separate. No charge is inferred when billing data is absent.","operationId":"get_v1_system_reports","parameters":[{"description":"Aggregate all matching requests; ignores pagination. Cannot combine with CSV.","in":"query","name":"view","schema":{"enum":["summary"],"type":"string"}},{"description":"Summary calendar buckets in the selected timezone. Weeks start Monday. A range of one month or less has one monthly bucket. Maximum 10000 buckets.","in":"query","name":"interval","schema":{"default":"day","enum":["day","week","month"],"type":"string"}},{"description":"Exact user ID or email (case-insensitive); financial viewers only.","in":"query","name":"user","schema":{"type":"string"}},{"description":"IANA time zone for inclusive from/to calendar dates; CSV timestamps remain UTC.","in":"query","name":"timezone","schema":{"default":"UTC","type":"string"}},{"description":"Export every matching row as CSV; limit and offset are ignored.","in":"query","name":"format","schema":{"enum":["csv"],"type":"string"}},{"in":"query","name":"user_id","schema":{"format":"uuid","type":"string"}},{"description":"First included date in the requested timezone; defaults to the start of this month.","in":"query","name":"from","schema":{"format":"date","type":"string"}},{"description":"Last included date in the requested timezone; defaults to today.","in":"query","name":"to","schema":{"format":"date","type":"string"}},{"in":"query","name":"api_key_id","schema":{"format":"uuid","type":"string"}},{"description":"Exact generation ID. Combined with the other filters.","in":"query","name":"generation_id","schema":{"format":"uuid","type":"string"}},{"in":"query","name":"limit","schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"offset","schema":{"default":0,"maximum":100000,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ReportSummary"},{"properties":{"data":{"items":{"properties":{"api_key_id":{"type":["string","null"]},"api_key_name":{"type":"string"},"consumed_usd":{"description":"Generation cost before package coverage; null while unknown.","type":["number","null"]},"cost":{"$ref":"#/components/schemas/TaskCost"},"created_at":{"format":"date-time","type":"string"},"id":{"format":"uuid","type":"string"},"identity_historical":{"description":"True when labels were captured at request acceptance. False for legacy current-directory fallbacks.","type":"boolean"},"identity_snapshot":{"additionalProperties":true,"type":"object"},"model":{"type":"string"},"organization_id":{"format":"uuid","type":"string"},"organization_name":{"type":"string"},"provider":{"type":"string"},"provider_name":{"type":"string"},"status":{"type":"string"},"usage":{"$ref":"#/components/schemas/ProviderUsage"},"user_email":{"type":"string"},"user_id":{"format":"uuid","type":"string"},"user_picture":{"description":"Current profile image for the authorized report user; historical identity labels remain unchanged.","format":"uri","type":"string"}},"type":"object"},"type":"array"},"has_more":{"type":"boolean"},"next_offset":{"type":"integer"}},"type":"object"}]}},"text/csv":{"example":"Created at (UTC),Cost (USD)","schema":{"type":"string"}}},"description":"Tasks in descending creation order."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read generation cost history across all organizations","tags":["System"],"x-required-scope":"system:manage","x-system-administrator-required":true}},"/v1/system/reports/{id}":{"get":{"description":"Requires a system administrator. Resolves the owning organization from the authorized Reports list; excludes private personal tasks. Returns every retained public generation field and exact saved request settings when content access is allowed. Minimal logging omits prompt, instructions, webhook and references, exposing only retained resolution, ratio, duration and generate_audio. Customer views retain the existing financial sanitization. Provider/storage credentials are never returned.","operationId":"get_v1_system_reports_id","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDetail"}}},"description":"Generation details authorized for this viewer"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No generation report in the authorized scope"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read full system-wide organization generation report","tags":["Reports"]}},"/v1/system/reports/{id}/content":{"get":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"get_v1_system_reports_id_content","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file content"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read system-wide organization generation result","tags":["Reports"]},"head":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"head_v1_system_reports_id_content","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file headers"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Inspect system-wide organization generation result","tags":["Reports"]}},"/v1/system/reports/{id}/last-frame":{"get":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"get_v1_system_reports_id_last_frame","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file content"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read system-wide organization generation last frame","tags":["Reports"]},"head":{"description":"Same report ownership and content permissions as the detail route. Supports browser sessions, Range and download=1. Deleted or unstored files return 404; direct storage may redirect to a temporary signed URL.","operationId":"head_v1_system_reports_id_last_frame","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"Download as an attachment","in":"query","name":"download","schema":{"enum":["1"],"type":"string"}}],"responses":{"200":{"description":"Stored file headers"},"206":{"description":"Partial file content"},"307":{"description":"Temporary signed storage URL"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"No authorized stored artifact"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Inspect system-wide organization generation last frame","tags":["Reports"]}},"/v1/system/resources/import":{"post":{"description":"Requires an administrator. Copies the caller's saved encrypted provider and S3 connections into empty shared settings. Does not overwrite existing shared connections, migrate files or enable sharing. Audited.","operationId":"post_v1_system_resources_import","responses":{"204":{"description":"Connections copied"},"403":{"description":"Administrator required"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Copy your personal connections to shared resources","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/sales":{"get":{"description":"Administrator browser session only. Includes all sales employees, including those reporting directly to Administrator or skipping a vacant rank. API keys are rejected.","operationId":"get__v1_system_sales","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesStructure"}}},"description":"Consistent hierarchy snapshot"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"sessionAuth":[]}],"summary":"Read the complete sales hierarchy","tags":["System"]}},"/v1/system/sales/bonus-settings":{"put":{"description":"Browser administrator only. Defaults are 5 percent for the assigned manager and 1 percent for their immediate actual supervisor. Sum cannot exceed 100 percent. Changes affect first recognition after saving; existing accruals keep their rate and recipients.","operationId":"put_sales_bonus_settings","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BonusSettings"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BonusSettings"}}},"description":"Saved settings"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Stale settings version"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"sessionAuth":[]}],"summary":"Set global sales bonus percentages","tags":["System"]}},"/v1/system/sales/{employee}":{"put":{"description":"Administrator browser session only. Requires the current global structure version. Supervisor must be a sales employee of strictly higher rank; empty means Administrator. Role and supervisor change atomically. Incompatible direct reports move to the selected supervisor, retaining their roles and clients. Other reports move with the employee. Existing personal client assignments survive sales-to-sales changes. Adding a non-sales user revokes their keys and is rejected for organization owners/managers and administrators. Changes are audited. API keys are rejected.","operationId":"put__v1_system_sales_employee","parameters":[{"in":"path","name":"employee","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"fill_vacancy":{"default":false,"description":"For lead/regional placement, atomically adopt lower-rank employees directly reporting to the selected supervisor. Cannot be combined with new_team. False preserves compatible direct reports.","type":"boolean"},"new_team":{"default":false,"description":"For lead/regional placement, move only the employee into an empty branch; former direct reports stay with the previous supervisor or Administrator. Works with unchanged role/supervisor. Cannot be combined with fill_vacancy.","type":"boolean"},"role":{"$ref":"#/components/schemas/SalesRole"},"supervisor_id":{"description":"Higher-rank employee UUID or empty for Administrator.","type":"string"},"version":{"minimum":1,"type":"integer"}},"required":["role","supervisor_id","version"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesStructure"}}},"description":"Saved hierarchy and its current version"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Employee not found"},"409":{"description":"Stale hierarchy or invalid role/supervisor placement"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"sessionAuth":[]}],"summary":"Add or move a sales employee and change their sales role","tags":["System"]}},"/v1/system/settings":{"get":{"description":"Requires a current administrator role and either a console session or a personal key with system:manage. Roles are checked on every request. Revoking the last administrator is rejected. Settings use version to prevent overwriting concurrent changes.","operationId":"get__v1_system_settings","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemSettings"}}},"description":"Successful response. Lists return up to 50 records."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"User not found"},"409":{"description":"Last administrator protection or stale settings version"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Read system settings","tags":["System"],"x-required-scope":"system:manage"},"put":{"description":"Requires a current administrator role and either a console session or a personal key with system:manage. Roles are checked on every request. Revoking the last administrator is rejected. Settings use version to prevent overwriting concurrent changes.","operationId":"put__v1_system_settings","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemSettings"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemSettings"}}},"description":"Successful response. Lists return up to 50 records."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"User not found"},"409":{"description":"Last administrator protection or stale settings version"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Update system settings","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/storage":{"get":{"description":"Returns the current local or S3 selection, connection fields and access key ID to authorized storage managers. The secret access key is never returned. Accounts default to local storage.","operationId":"get_v1_system_storage","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageSettings"}}},"description":"Storage settings"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Shared — Read account storage settings","tags":["System"],"x-required-scope":"system:manage","x-system-administrator-required":true},"put":{"description":"Tests S3 object write, read and delete permissions before activating. Checks browser preflights for configured UI_PUBLIC_URL (or API_PUBLIC_URL), falling back to the request Origin. Missing CORS is configured automatically using the saved key, preserving other rules and bucket privacy; CORS read/update rights are required only for missing browser access. After confirming the saved policy, browser_uploads_pending can be true while provider caches apply the change. Changes apply when results are archived, without restarting the worker. Existing files remain at their original location. Blank credentials preserve saved values; changing endpoint requires both credentials again. Selecting local preserves the last S3 connection. Maximum request body is 16 KiB.","operationId":"put_v1_system_storage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageSettings"}}},"description":"Saved settings"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Shared — Configure account storage","tags":["System"],"x-required-scope":"system:manage","x-system-administrator-required":true}},"/v1/system/storage/check":{"post":{"description":"Creates, reads and deletes a uniquely named temporary object under the configured prefix. Does not list or create buckets. Uses saved credentials if omitted. A successful check does not activate the settings. Also validates PUT/GET/HEAD browser preflights for configured UI_PUBLIC_URL (or API_PUBLIC_URL), falling back to the request Origin. Without either, retains the server-only probe. Missing browser access returns storage_browser_setup_required. No bucket CORS is changed.","operationId":"post_v1_system_storage_check","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageUpdate"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"status":{"const":"ok","type":"string"}},"type":"object"}}},"description":"Connection verified"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Shared — Test proposed storage settings without saving","tags":["System"],"x-required-scope":"system:manage","x-system-administrator-required":true}},"/v1/system/storage/quota":{"get":{"operationId":"getSharedStorageQuota","responses":{"200":{"description":"Object with limit_bytes (nullable integer) and version."},"403":{"$ref":"#/components/responses/Forbidden"}},"summary":"Read the global per-user shared-storage allowance","tags":["System"],"x-required-scope":"system:manage"},"put":{"description":"Requires a current administrator. Only new uploads and generations are blocked when current usage already exceeds the limit. Accepted tasks always archive their results. Does not change monetary budgets or delete any files.","operationId":"setSharedStorageQuota","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"limit_bytes":{"maximum":1000000000000000,"minimum":0,"type":["integer","null"]},"version":{"minimum":1,"type":"integer"}},"required":["limit_bytes","version"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Updated limit_bytes and version."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"Settings changed; reload before saving."}},"summary":"Set the global per-user shared-storage allowance","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/users":{"get":{"description":"Requires a current administrator role and either a console session or a personal key with system:manage. Roles are checked on every request. Revoking the last administrator is rejected. Settings use version to prevent overwriting concurrent changes.","operationId":"get__v1_system_users","parameters":[{"in":"query","name":"offset","schema":{"default":0,"maximum":100000,"minimum":0,"type":"integer"}},{"in":"query","name":"search","schema":{"maxLength":200,"type":"string"}},{"in":"query","name":"admins_only","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemUserPage"}}},"description":"Successful response. Lists return up to 50 records."},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"User not found"},"409":{"description":"Last administrator protection or stale settings version"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Find users and administrators","tags":["System"],"x-required-scope":"system:manage"}},"/v1/system/users/{id}/role":{"put":{"description":"Requires a current administrator role and either a console session or a personal key with system:manage. Roles are checked on every request. Revoking the last administrator is rejected. Settings use version to prevent overwriting concurrent changes.","operationId":"put__v1_system_users_id_role","parameters":[{"in":"path","name":"id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"oneOf":[{"required":["role"]},{"required":["is_system_admin"]},{"required":["is_client_manager"]}],"properties":{"is_client_manager":{"description":"Read-only assigned-organization access. Enabling revokes existing keys; disabling clears assignments. Remove administrator roles first.","type":"boolean"},"is_system_admin":{"type":"boolean"},"role":{"description":"Atomic role transition.","enum":["user","system_admin","client_manager","lead_client_manager","regional_client_manager"],"type":"string"}},"type":"object"}}},"required":true},"responses":{"204":{"description":"Role updated"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"User not found"},"409":{"description":"Last administrator protection or stale settings version"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"security":[{"bearerAuth":[]},{"sessionAuth":[]}],"summary":"Grant or revoke administrator access","tags":["System"],"x-required-scope":"system:manage"}},"/v1/videos":{"post":{"description":"Returns HTTP 202 immediately after queue admission. Poll status_url until completed/failed; download content_url with the same API key. Provider execution never runs synchronously in this request. This endpoint selects media_type=video. Multipart uploads are local-storage only, with a 32 MiB total limit. S3 returns 409 direct_upload_required; upload with /v1/references/uploads and send JSON referencing that file. Local uploads are saved to the reference library; uploaded files remain reusable even if later generation admission fails. Use image/image[] for edits, input_reference for video. options is JSON text.","operationId":"post_v1_videos","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationRequest"}},"multipart/form-data":{"schema":{"properties":{"input_reference":{"format":"binary","type":"string"},"model":{"type":"string"},"options":{"description":"JSON-encoded MediaOptions","type":"string"},"prompt":{"type":"string"},"seconds":{"type":"string"},"size":{"type":"string"},"timeout_seconds":{"format":"int64","maximum":9223372036,"minimum":1,"type":"integer"}},"required":["model","prompt","input_reference"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}},"description":"Generation accepted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Budget exceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Idempotency conflict or changed estimate"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Pricing unavailable"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Create a video","tags":["Generations"],"x-required-scope":"generation"}},"/v1/videos/{id}":{"get":{"description":"Owner-scoped status. The video route returns 404 for other media types. All routes use the same statuses and Unix timestamps.","operationId":"get_v1_videos_id","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generation"}}},"description":"Generation"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Generation not found"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Retrieve asynchronous generation","tags":["Generations"]},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}]},"/v1/videos/{id}/content":{"get":{"description":"Authenticated result download using existing storage, Range and deletion behavior. Until a result is stored, no media is returned.","operationId":"get_v1_videos_id_content","responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"Stored media"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Result not available"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not ready"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Download generation content","tags":["Media"]},"head":{"description":"Authenticated result download using existing storage, Range and deletion behavior. Until a result is stored, no media is returned.","operationId":"head_v1_videos_id_content","responses":{"200":{"content":{"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"Stored media"},"206":{"description":"Partial content"},"307":{"description":"S3 file; follow the signed storage URL without forwarding Gateway credentials. S3 serves file bytes and Range requests directly.","headers":{"Location":{"schema":{"format":"uri","type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Result not available"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not ready"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Inspect generation content","tags":["Media"]},"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}]}},"security":[{"bearerAuth":[]}],"servers":[{"description":"Gateway API","url":"https://media-gateway.sunday.games"}],"tags":[{"name":"Generations"},{"name":"Catalog"},{"name":"Media"},{"name":"References"},{"name":"Providers admin"},{"name":"Storage admin"},{"name":"Storage"},{"name":"API keys"},{"name":"Reports"},{"name":"Audit"},{"name":"Account"},{"name":"System"},{"name":"Organizations"},{"name":"Payments"}],"webhooks":{"taskEvent":{"post":{"description":"Sent to the webhook_url on the task. Delivery may repeat or arrive out of order. Verify the timestamp and HMAC-SHA256 signature over timestamp + a period + raw body using the deployment WEBHOOK_SIGNING_SECRET. This version has a deployment-wide signing secret, provisioned by the operator, not a per-account secret API.","parameters":[{"description":"Stable delivery ID; deduplicate this value.","in":"header","name":"X-Media-Gateway-Delivery","required":true,"schema":{"type":"string"}},{"description":"Task lifecycle event name.","in":"header","name":"X-Media-Gateway-Event","required":true,"schema":{"type":"string"}},{"description":"Unix timestamp in seconds.","in":"header","name":"X-Media-Gateway-Timestamp","required":true,"schema":{"type":"string"}},{"description":"v1= followed by lowercase hex HMAC-SHA256.","in":"header","name":"X-Media-Gateway-Signature","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Any 2xx acknowledges durable acceptance. Non-2xx and network failures are retried with bounded exponential backoff."}},"security":[],"summary":"Task lifecycle notification"}}}}