{ "openapi": "3.1.0", "info": { "title": "xconvert Public API", "version": "1", "summary": "Programmatic access to xconvert's conversion engine.", "description": "The xconvert Public API gives customers programmatic access to\nevery conversion feature available in the xconvert web app.\n\n## Authentication\n\nEvery request must carry an `Authorization: Bearer ` header.\nKeys are issued via the portal and have the form\n`xck_live_` (production) or `xck_test_` (test). See\n§5.1 for the full key lifecycle.\n\n## Versioning\n\nAll routes live under `/v1/public/`. The API version is also\nechoed on every response as `x-xconvert-api-version: 1`. New\nfields + new routes are additive (minor version bumps do not\nbreak clients); removal or semantic changes bump the major\nversion.\n\n## Error envelope\n\nEvery 4xx / 5xx response uses RFC 9457 Problem Details with\n`Content-Type: application/problem+json`. See the `Error\ncatalog` tag for the full list of stable `code` values.\n\n## Source of truth\n\nThis document is the hand-authored index per\n`developer-api.md` §5.11. Per-feature option schemas live in\nsibling files under `public/openapi/v1/features/` and are\n`$ref`'d from this index. That split keeps the index small\n(~100 KB) while supporting xconvert's ~5,250 features.\n", "contact": { "name": "xconvert developer support", "url": "https://xconvert.com/docs/api", "email": "api@xconvert.com" }, "license": { "name": "Proprietary", "url": "https://xconvert.com/legal/api-terms" }, "x-xconvert-stripped-feature-request-schemas": 5215 }, "servers": [ { "url": "https://api.xconvert.com", "description": "Production API root" }, { "url": "https://api.staging.xconvert.com", "description": "Staging API root (test keys only)" } ], "security": [ { "bearerApiKey": [] } ], "tags": [ { "name": "Caller introspection", "description": "`/v1/public/me` returns everything the caller could want to\nconfirm about their session — key metadata, resolved tier,\ncredit balances, plan + feature limits. Safe to call on\nevery client startup; cheap and unmetered.\n" }, { "name": "API keys", "description": "Customer CRUD on their own API keys per §5.2. Never returns\nthe secret after the one-time create / rotate disclosure.\n" }, { "name": "Jobs", "description": "Submit conversion jobs and poll their status per §5.3.\n`POST /v1/public/jobs` is the core primitive; `GET /v1/public/jobs`\nand `/v1/public/jobs/{id}` support async polling with strong\nETags for cheap re-reads.\n" }, { "name": "Uploads", "description": "Signed-URL handoff to ironman edge per §5.6. The facade\nissues a one-time signed chunk endpoint; clients upload\ndirectly to edge, then call `/complete`.\n" }, { "name": "Webhooks (customer)", "description": "Customer-facing webhook endpoint CRUD per §5.5. Includes\n`/resume`, `/acknowledge-secret`, and `/rotate-secret`.\n" }, { "name": "Webhooks (admin)", "description": "Admin-only webhook operations per §5.5.4: `/pause`,\n`/unpause`, `/force-rotate`. Require the `webhooks:admin`\nscope.\n" }, { "name": "Features", "description": "Dry-run option validator per §5.2.7. Returns normalized\noptions + `appliedDefaults[]` on success, structured\n`errors[]` on failure. Unmetered.\n" }, { "name": "Admin credits", "description": "Admin-initiated per-workflow refund per §1 Credit refunds.\nRequires the `credits:refund` scope (bulk requires\n`credits:refund_bulk`). v1: 501 stub pending Billing V2.\n" }, { "name": "Admin GDPR", "description": "Admin-only GDPR erasure endpoint per §13.9. v1: 501 stub\npending the erasure pipeline.\n" }, { "name": "Admin schemas", "description": "CI-pushed feature-schema publish endpoint per §5.2.6. Scope\n`schemas:publish`.\n" } ], "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "xck_live_*", "description": "xconvert API key. Production keys start with `xck_live_`;\ntest keys start with `xck_test_`. Test keys never hit\nproduction billing and never accept prod edge fleets.\n" } }, "headers": { "XRequestId": { "description": "Per-request correlation id. The server generates one if\nthe client doesn't send an `X-Request-Id`; the value is\nechoed on every response for log correlation.\n", "schema": { "type": "string", "example": "req_01HQW7Z6W3FYR2PQZV9H5KXWY4" } }, "XXconvertApiVersion": { "description": "Always `1` in v1.", "schema": { "type": "string", "example": "1" } }, "XXconvertCreditsUsed": { "description": "Credits debited for this call. `0` for introspection / validate / GET endpoints.", "schema": { "type": "integer", "minimum": 0 } }, "XXconvertCreditsRemaining": { "description": "Combined balance across all pools after this call.", "schema": { "type": "integer" } }, "XXconvertCreditsSubscriptionRemaining": { "description": "Remaining credits in the subscription pool.", "schema": { "type": "integer" } }, "XXconvertCreditsPaygRemaining": { "description": "Remaining credits in the PAYG top-up pool.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Number of seconds the client should wait before retrying.", "schema": { "type": "integer", "minimum": 1 } }, "ETag": { "description": "Strong entity tag per §5.4 (SHA-256 first 16 chars of canonical body).", "schema": { "type": "string", "example": "\"a7f3b1c8e9d2f456\"" } } }, "schemas": { "ProblemDetails": { "type": "object", "description": "RFC 9457 Problem Details + xconvert extensions per §5.10.", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri", "description": "Stable URL per error class.", "example": "https://xconvert.com/docs/errors/insufficient_credits" }, "title": { "type": "string", "description": "Short human-readable summary, stable per `code`.", "example": "Insufficient credits" }, "status": { "type": "integer", "description": "HTTP status code.", "example": 402 }, "detail": { "type": "string", "description": "Dynamic human-readable description of this specific error." }, "instance": { "type": "string", "description": "The request path.", "example": "/v1/public/jobs" }, "code": { "type": "string", "description": "Stable machine-readable identifier. Clients switch on\n`code`, not `title` or `detail`. See the full catalog\nin §5.10.\n", "enum": [ "malformed_request", "invalid_cursor", "unauthenticated", "key_revoked", "key_expired", "ip_not_allowed", "insufficient_credits", "insufficient_scope", "account_suspended", "not_found", "feature_unknown", "idempotency_key_conflict", "webhook_endpoint_limit_reached", "invalid_transition", "endpoint_disabled", "job_state_conflict", "feature_removed", "file_too_large", "unsupported_media_type", "option_validation_failed", "feature_input_mismatch", "input_file_expired", "body_mismatch_on_idempotent_retry", "rate_limited", "concurrency_limit_reached", "internal_error", "output_unavailable", "upstream_edge_error", "billing_unavailable", "scheduler_unavailable", "maintenance" ] }, "requestId": { "type": "string", "description": "Same value as the `x-request-id` response header." } }, "additionalProperties": true }, "MeResponse": { "type": "object", "required": [ "userId", "accountType", "workflowSource", "apiTier", "apiKeyId", "apiKeyPrefix", "apiKeyScopes", "requestId", "credits", "planLimits", "featureLimits" ], "properties": { "userId": { "type": "string", "description": "Owning user's hex ObjectId." }, "organizationId": { "type": "string", "nullable": true }, "accountType": { "type": "string", "enum": [ "USER", "ORG" ] }, "workflowSource": { "type": "string", "enum": [ "api_key", "website" ], "description": "Always `api_key` from the public API surface. Matches\nthe `WorkflowSource` enum's on-wire value.\n" }, "apiTier": { "type": "string", "enum": [ "API_STARTER", "API_PRO", "API_SCALE", "API_NO_CREDITS" ] }, "apiKeyId": { "type": "string" }, "apiKeyPrefix": { "type": "string", "example": "xck_live_abc123" }, "apiKeyScopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "requestId": { "type": "string" }, "credits": { "$ref": "#/components/schemas/MeCredits" }, "planLimits": { "type": "object", "description": "Per-plan limits. v1 returns `{}` until Settings plumbing wires real values.", "additionalProperties": true }, "featureLimits": { "type": "object", "description": "Per-feature caps. v1 returns `{}` until feature-registry integration ships.", "additionalProperties": true } } }, "MeCredits": { "type": "object", "description": "v1 returns zeros for all three counters until Billing V2\nwires real values.\n", "required": [ "used_30d", "subscription_remaining", "payg_remaining" ], "properties": { "used_30d": { "type": "integer", "format": "int64", "minimum": 0 }, "subscription_remaining": { "type": "integer", "format": "int64" }, "payg_remaining": { "type": "integer", "format": "int64" } } }, "ApiKeySummary": { "type": "object", "description": "Customer-visible API key summary. Never includes the secret after create / rotate.", "required": [ "id", "createdByUserId", "name", "prefix", "scopes", "createdAt" ], "properties": { "id": { "type": "string" }, "userId": { "type": "string", "nullable": true }, "organizationId": { "type": "string", "nullable": true }, "createdByUserId": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "example": "xck_live_abc123" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastUsedIp": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true }, "revokedReason": { "type": "string", "nullable": true } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 64 }, "preset": { "type": "string", "enum": [ "read-only", "full" ], "description": "Convenience scope selector. `read-only` grants\n`jobs:read features:read account:read webhooks:read`;\n`full` adds the write variants. Overridden by `scopes`\nif both are provided.\n" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "allowedIpRanges": { "type": "array", "items": { "type": "string", "description": "CIDR block" } } } }, "CreateApiKeyResponse": { "type": "object", "required": [ "apiKey", "secret" ], "properties": { "apiKey": { "$ref": "#/components/schemas/ApiKeySummary" }, "secret": { "type": "string", "description": "The full token (prefix + secret body). Returned ONCE\nat create time; never surfaced again. Clients must\nstore it immediately.\n", "example": "xck_live_abc123xyz..." } } }, "RotateApiKeyResponse": { "type": "object", "required": [ "id", "secret" ], "properties": { "id": { "type": "string" }, "secret": { "type": "string" }, "previousSecretExpiresAt": { "type": "string", "format": "date-time", "nullable": true } } }, "CreateJobRequest": { "type": "object", "description": "See §5.3.1. v1 requires explicit `fromType`/`toType`/\n`processType` hints until the feature-metadata loader\nships (§10.5n).\n", "required": [ "featureId", "fileIds", "fromType", "toType", "processType" ], "properties": { "featureId": { "type": "string" }, "options": { "type": "object", "additionalProperties": true }, "fileIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "schemaVersion": { "type": "integer", "nullable": true }, "wait": { "type": "boolean", "default": false }, "webhookEndpointId": { "type": "string", "nullable": true }, "fromType": { "type": "string" }, "toType": { "type": "string" }, "processType": { "type": "string" } } }, "CreateJobResponse": { "type": "object", "required": [ "id", "status", "featureId", "createdAt", "estimatedCreditsCost", "submittedOptions", "normalizedOptions" ], "properties": { "id": { "type": "string", "example": "job_01HQW7Z6W3FYR2PQZV9H5KXWY4" }, "status": { "type": "string", "enum": [ "queued", "processing", "complete", "failed", "canceled" ] }, "featureId": { "type": "string" }, "schemaVersion": { "type": "integer", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "estimatedCreditsCost": { "type": "integer", "format": "int64" }, "submittedOptions": { "type": "object", "additionalProperties": true }, "normalizedOptions": { "type": "object", "additionalProperties": true }, "webhookEndpointId": { "type": "string", "nullable": true } } }, "Job": { "type": "object", "description": "Read shape for `GET /v1/public/jobs/{id}` and list items.", "required": [ "id", "status", "submittedOptions", "normalizedOptions", "credits" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "processing", "complete", "failed", "canceled" ] }, "featureId": { "type": "string", "nullable": true }, "schemaVersion": { "type": "integer", "nullable": true }, "progress": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1 }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/JobOutput" } }, "error": { "type": "object", "nullable": true, "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "canceledAt": { "type": "string", "format": "date-time", "nullable": true }, "submittedOptions": { "type": "object", "additionalProperties": true }, "normalizedOptions": { "type": "object", "additionalProperties": true }, "credits": { "$ref": "#/components/schemas/JobCredits" } } }, "JobOutput": { "type": "object", "required": [ "index", "filename", "downloadUrl" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "filename": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64", "nullable": true }, "contentType": { "type": "string", "nullable": true }, "downloadUrl": { "type": "string" } } }, "JobCredits": { "type": "object", "required": [ "used", "remaining", "subscriptionRemaining", "paygRemaining" ], "properties": { "used": { "type": "integer", "format": "int64" }, "remaining": { "type": "integer", "format": "int64" }, "subscriptionRemaining": { "type": "integer", "format": "int64" }, "paygRemaining": { "type": "integer", "format": "int64" } } }, "JobListResponse": { "type": "object", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } }, "CreateUploadRequest": { "type": "object", "required": [ "featureId", "files" ], "properties": { "featureId": { "type": "string" }, "files": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/UploadFileRequest" } } } }, "UploadFileRequest": { "type": "object", "required": [ "name", "sizeBytes" ], "properties": { "name": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64", "minimum": 0 }, "contentType": { "type": "string", "nullable": true } } }, "CreateUploadResponse": { "type": "object", "required": [ "uploadId", "uploads" ], "properties": { "uploadId": { "type": "string" }, "uploads": { "type": "array", "items": { "$ref": "#/components/schemas/UploadHandoff" } } } }, "UploadHandoff": { "type": "object", "required": [ "fileId", "chunkEndpoint", "maxChunkBytes", "expiresAt" ], "properties": { "fileId": { "type": "string" }, "chunkEndpoint": { "type": "string", "format": "uri" }, "maxChunkBytes": { "type": "integer", "format": "int64" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "CompleteUploadResponse": { "type": "object", "required": [ "uploadId", "status", "files" ], "properties": { "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "canceled" ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "fileId", "name", "sizeBytes" ], "properties": { "fileId": { "type": "string" }, "name": { "type": "string" }, "sizeBytes": { "type": "integer", "format": "int64" } } } } } }, "DeleteUploadResponse": { "type": "object", "required": [ "uploadId", "status" ], "properties": { "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "canceled" ] } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "url", "enabledEvents", "status", "maxConcurrentDeliveries", "inFlightDeliveryCount" ], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabledEvents": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "stopped_by_user", "paused_by_admin", "circuit_open", "pending_secret_ack", "disabled" ] }, "statusChangedAt": { "type": "string", "format": "date-time", "nullable": true }, "statusChangedBy": { "$ref": "#/components/schemas/StatusActor" }, "maxConcurrentDeliveries": { "type": "integer" }, "inFlightDeliveryCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time", "nullable": true } } }, "StatusActor": { "type": "object", "nullable": true, "required": [ "actorId", "actorType" ], "properties": { "actorId": { "type": "string" }, "actorType": { "type": "string", "enum": [ "user", "admin", "system" ] } } }, "CreateWebhookEndpointRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "enabledEvents": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "nullable": true }, "maxConcurrentDeliveries": { "type": "integer", "minimum": 1, "maximum": 100, "nullable": true } } }, "PatchWebhookEndpointRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "nullable": true }, "enabledEvents": { "type": "array", "items": { "type": "string" }, "nullable": true }, "description": { "type": "string", "nullable": true }, "maxConcurrentDeliveries": { "type": "integer", "minimum": 1, "maximum": 100, "nullable": true } } }, "CreateWebhookEndpointResponse": { "type": "object", "required": [ "endpoint", "secret" ], "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "type": "string", "description": "`whsec_` per §5.5.4." } } }, "RotateSecretResponse": { "type": "object", "required": [ "id", "secret" ], "properties": { "id": { "type": "string" }, "secret": { "type": "string" }, "previousSecretExpiresAt": { "type": "string", "format": "date-time", "nullable": true } } }, "WebhookEndpointListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "ValidateFeatureRequest": { "type": "object", "properties": { "options": { "type": "object", "additionalProperties": true }, "schemaVersion": { "type": "integer", "nullable": true, "description": "Required in v1 (findLatest is a future follow-up)." } } }, "ValidateFeatureResponse": { "type": "object", "required": [ "valid", "featureId", "schemaVersion", "submittedOptions" ], "properties": { "valid": { "type": "boolean" }, "featureId": { "type": "string" }, "schemaVersion": { "type": "integer" }, "submittedOptions": { "type": "object", "additionalProperties": true }, "normalizedOptions": { "type": "object", "additionalProperties": true, "nullable": true }, "appliedDefaults": { "type": "array", "nullable": true, "items": { "type": "object", "required": [ "propertyName", "source" ], "properties": { "propertyName": { "type": "string" }, "value": {}, "source": { "type": "string", "example": "schema_default" } } } }, "errors": { "type": "array", "nullable": true, "items": { "type": "object", "required": [ "propertyPath", "code", "message" ], "properties": { "propertyPath": { "type": "string" }, "code": { "type": "string", "enum": [ "enum_mismatch", "required_in_context", "unknown_property", "type_mismatch", "format_mismatch", "range_violation", "validation_failed" ] }, "message": { "type": "string" }, "got": {}, "allowedValues": { "type": "array", "items": {} }, "contextRule": { "type": "string", "nullable": true }, "suggestion": { "type": "string", "nullable": true } } } } } }, "CreditRefundRequest": { "type": "object", "required": [ "workflowId", "reason" ], "properties": { "workflowId": { "type": "string" }, "reason": { "type": "string" }, "workflowIds": { "type": "array", "items": { "type": "string" }, "description": "Future bulk-refund shape. Requires `credits:refund_bulk` scope." } } }, "GdprErasureRequest": { "type": "object", "required": [ "userId", "reason", "regulatorReference", "scope" ], "properties": { "userId": { "type": "string" }, "reason": { "type": "string" }, "regulatorReference": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string", "enum": [ "api_keys", "jobs", "webhook_endpoints", "normalized_options_pii", "all" ] }, "minItems": 1 } } }, "PublishSchemasRequest": { "type": "object", "description": "Used by xconfig CI per §5.2.6. Owned by that track; shape reserved here.", "additionalProperties": true }, "PublishSchemasResponse": { "type": "object", "additionalProperties": true }, "WebhookEventEnvelope": { "type": "object", "required": [ "id", "type", "envelopeVersion", "apiVersion", "createdAt", "accountId", "accountType", "data" ], "properties": { "id": { "type": "string", "example": "evt_01HQW7Z6W3FYR2PQZV9H5KXWY4" }, "type": { "type": "string", "enum": [ "job.created", "job.processing", "job.completed", "job.failed", "job.canceled", "credit.warning", "credit.cap_reached", "credit.exhausted", "credit.refunded", "api_key.expiring" ] }, "envelopeVersion": { "type": "integer", "example": 1 }, "apiVersion": { "type": "string", "example": "1" }, "createdAt": { "type": "string", "format": "date-time" }, "accountId": { "type": "string" }, "accountType": { "type": "string", "enum": [ "USER", "ORG" ] }, "data": { "type": "object", "additionalProperties": true } } }, "BillingOverview": { "type": "object", "properties": { "userId": { "type": "string" }, "entitlements": { "type": "array", "items": { "$ref": "#/components/schemas/EntitlementSummary" } }, "creditBalances": { "type": "array", "items": { "$ref": "#/components/schemas/CreditBalanceEntry" } }, "combinedBalance": { "type": "integer", "format": "int64", "description": "Sum across pools. Signed — can be negative when established\nusers are in overage on API_PAYG (within the global hard limit).\n" }, "apiBillingEstablished": { "type": "boolean", "description": "True after the user's first paid API purchase per §F4." }, "nextExpiringGrantAt": { "type": "string", "format": "date-time", "nullable": true } } }, "EntitlementSummary": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "WEBSITE", "API" ] }, "packageType": { "type": "string" }, "state": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "PAST_DUE", "CANCELED_ACCESS_UNTIL_PERIOD_END", "EXPIRED" ] }, "activeUntil": { "type": "string", "format": "date-time", "nullable": true }, "subscriptionRef": { "type": "string", "nullable": true } } }, "CreditBalanceEntry": { "type": "object", "properties": { "pool": { "type": "string", "enum": [ "API_SUBSCRIPTION_MONTHLY", "API_PAYG" ] }, "availableCredits": { "type": "integer", "format": "int64" }, "nextExpiringAt": { "type": "string", "format": "date-time", "nullable": true } } }, "BillingHistoryResponse": { "type": "object", "properties": { "limit": { "type": "integer" }, "skip": { "type": "integer" }, "count": { "type": "integer" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentEventRow" } } } }, "PaymentEventRow": { "type": "object", "properties": { "id": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "eventType": { "type": "string" }, "provider": { "type": "string", "enum": [ "STRIPE", "PAYPAL" ], "nullable": true }, "amountCents": { "type": "integer", "format": "int64", "nullable": true }, "currency": { "type": "string", "nullable": true }, "description": { "type": "string" }, "actor": { "type": "string", "enum": [ "USER", "WEBHOOK", "ADMIN", "CRON", "BACKFILL" ] }, "subscriptionRef": { "type": "string", "nullable": true }, "grantRef": { "type": "string", "nullable": true } } }, "BillingUsageResponse": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "totalCalls": { "type": "integer", "format": "int64" }, "totalCreditsDebited": { "type": "integer", "format": "int64" }, "byFeature": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "description": "Conversion-pattern → credits map." }, "byApiKey": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "description": "ApiKey id (hex) → credits map." } } }, "BillingGrantsResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/CreditGrantRow" } } } }, "CreditGrantRow": { "type": "object", "properties": { "id": { "type": "string" }, "pool": { "type": "string", "enum": [ "API_SUBSCRIPTION_MONTHLY", "API_PAYG" ] }, "type": { "type": "string", "enum": [ "PAID_TOPUP", "SUBSCRIPTION_ALLOTMENT", "ADMIN_PROMO", "REFUND_REVERSAL" ] }, "creditsGranted": { "type": "integer", "format": "int64" }, "creditsRemaining": { "type": "integer", "format": "int64" }, "amountCents": { "type": "integer", "format": "int64", "nullable": true }, "currency": { "type": "string", "nullable": true }, "grantedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "expired": { "type": "boolean" } } }, "BillingExport": { "type": "object", "properties": { "exportedAt": { "type": "string", "format": "date-time" }, "userId": { "type": "string" }, "since": { "type": "string", "format": "date-time", "nullable": true }, "until": { "type": "string", "format": "date-time", "nullable": true }, "eventCount": { "type": "integer" }, "grantCount": { "type": "integer" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentEventRow" } }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/CreditGrantRow" } } } }, "TopupRequest": { "type": "object", "required": [ "packId" ], "properties": { "packId": { "type": "string", "enum": [ "STARTER", "DEVELOPER", "PRO", "TEAM" ] } } }, "TopupResponse": { "type": "object", "properties": { "checkoutUrl": { "type": "string", "format": "uri" }, "packId": { "type": "string" }, "credits": { "type": "integer", "format": "int64" }, "amountCents": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "example": "USD" } } }, "TopupPacksResponse": { "type": "object", "properties": { "packs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "credits": { "type": "integer", "format": "int64" }, "priceCents": { "type": "integer", "format": "int64" }, "currency": { "type": "string" } } } } } }, "ApiSubscriptionRequest": { "type": "object", "required": [ "planId" ], "properties": { "planId": { "type": "string", "enum": [ "API_STARTER", "API_PRO", "API_SCALE" ] } } }, "ApiSubscriptionResponse": { "type": "object", "properties": { "checkoutUrl": { "type": "string", "format": "uri" }, "planId": { "type": "string" }, "monthlyPriceCents": { "type": "integer", "format": "int64" }, "monthlyCredits": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "example": "USD" } } }, "ApiSubscriptionPlansResponse": { "type": "object", "properties": { "plans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "tier": { "type": "string" }, "monthlyCredits": { "type": "integer", "format": "int64" }, "monthlyPriceCents": { "type": "integer", "format": "int64" }, "currency": { "type": "string" } } } } } }, "ApiSubscriptionCancelResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "cancel_at_period_end_scheduled", "no_active_subscription", "expired" ] }, "providerSubscriptionId": { "type": "string", "nullable": true }, "activeUntil": { "type": "string", "format": "date-time", "nullable": true }, "message": { "type": "string" } } }, "AdminGrantEntitlementRequest": { "type": "object", "required": [ "type", "packageType", "reason" ], "properties": { "type": { "type": "string", "enum": [ "WEBSITE", "API" ] }, "packageType": { "type": "string" }, "activeUntil": { "type": "string", "format": "date-time", "nullable": true }, "reason": { "type": "string", "description": "Audit-trail reason; required." } } }, "AdminRevokeEntitlementRequest": { "type": "object", "required": [ "type", "reason" ], "properties": { "type": { "type": "string", "enum": [ "WEBSITE", "API" ] }, "reason": { "type": "string" } } }, "AdminGrantCreditsRequest": { "type": "object", "required": [ "pool", "credits", "reason" ], "properties": { "pool": { "type": "string", "enum": [ "API_SUBSCRIPTION_MONTHLY", "API_PAYG" ] }, "credits": { "type": "integer", "format": "int64", "minimum": 1 }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "reason": { "type": "string" } } }, "AdminBulkGrantRequest": { "type": "object", "required": [ "userIds", "pool", "credits", "reason" ], "properties": { "userIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 1000 }, "pool": { "type": "string", "enum": [ "API_SUBSCRIPTION_MONTHLY", "API_PAYG" ] }, "credits": { "type": "integer", "format": "int64", "minimum": 1 }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "reason": { "type": "string" } } } }, "responses": { "NoContent": { "description": "Success; no body." }, "Problem": { "description": "RFC 9457 Problem Details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Unauthorized": { "description": "Missing or invalid `Authorization` header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Forbidden": { "description": "Scope missing. `extensions.requiredScope` lists the needed scope.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotFound": { "description": "Resource missing or not accessible to the caller.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "Conflict": { "description": "State-machine conflict (idempotency, invalid transition, endpoint disabled, …).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "ValidationFailed": { "description": "Option / input validation failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "InsufficientCredits": { "description": "Caller would drop below hard limit after the debit.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "RateLimited": { "description": "Rate / concurrency limit hit. `Retry-After` header set.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "InternalError": { "description": "Unexpected server error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "NotImplemented": { "description": "v1 stub; feature not yet implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "webhooks": { "job.created": { "post": { "summary": "Job accepted (not yet processing).", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } }, "job.processing": { "post": { "summary": "Job claimed by a worker (at most once per job).", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } }, "job.completed": { "post": { "summary": "Terminal success.", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } }, "job.failed": { "post": { "summary": "Terminal failure.", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } }, "job.canceled": { "post": { "summary": "Canceled by user / client disconnect / admin.", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } }, "credit.warning": { "post": { "summary": "Subscription pool consumption crossed 75%. Fires once per cycle.", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } }, "credit.cap_reached": { "post": { "summary": "Subscription pool hit zero.", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } }, "credit.exhausted": { "post": { "summary": "Combined balance crossed zero.", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } }, "credit.refunded": { "post": { "summary": "Admin-issued credit refund for a specific workflow.", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } }, "api_key.expiring": { "post": { "summary": "Key's `expiresAt` is within 7 days.", "tags": [ "Webhooks (customer)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventEnvelope" } } } }, "responses": { "200": { "description": "Receiver acknowledged." } } } } }, "paths": { "/v1/public/me": { "get": { "tags": [ "Caller introspection" ], "summary": "Return caller identity + tier + scopes + credits.", "description": "Cheap, unmetered; safe to call on every client startup per\n§5.2. No additional scope required — any valid key works.\n", "operationId": "getMe", "responses": { "200": { "description": "Caller introspection.", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/v1/public/me' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst me = await xc.me.getMe();\nconsole.log(me.apiTier, me.credits.payg_remaining);" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.caller_introspection import get_me\nme = get_me.sync(client=xc.http)\nprint(me.api_tier, me.credits_.payg_remaining)" } ] } }, "/v1/public/api-keys": { "get": { "tags": [ "API keys" ], "summary": "List the caller's API keys.", "operationId": "listApiKeys", "parameters": [ { "in": "query", "name": "includeRevoked", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "List of API keys.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeySummary" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/v1/public/api-keys' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst keys = await xc.apiKeys.listApiKeys({});" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.api_keys import list_api_keys\nkeys = list_api_keys.sync(client=xc.http)" } ] }, "post": { "tags": [ "API keys" ], "summary": "Create a new API key.", "description": "Returns the secret exactly once. Store it immediately.", "operationId": "createApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/api-keys' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst created = await xc.apiKeys.createApiKey({\n requestBody: { name: 'ci-key', preset: 'full' },\n});\nconsole.log(created.secret); // shown ONCE; store it now" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.api_keys import create_api_key\nfrom xconvert.v1.generated.models.create_api_key_request import CreateApiKeyRequest\ncreated = create_api_key.sync(client=xc.http, body=CreateApiKeyRequest(name=\"ci-key\", preset=\"full\"))\nprint(created[\"secret\"]) # shown ONCE; store it now" } ] } }, "/v1/public/api-keys/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "API keys" ], "summary": "Get a single API key (never returns the secret).", "operationId": "getApiKey", "responses": { "200": { "description": "Summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeySummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/v1/public/api-keys/:id' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst key = await xc.apiKeys.getApiKey({ id });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.api_keys import get_api_key\nkey = get_api_key.sync(id=key_id, client=xc.http)" } ] }, "delete": { "tags": [ "API keys" ], "summary": "Soft-revoke the key. Idempotent.", "operationId": "revokeApiKey", "responses": { "200": { "description": "Revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeySummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X DELETE 'https://api.xconvert.com/v1/public/api-keys/:id' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nawait xc.apiKeys.revokeApiKey({ id });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.api_keys import revoke_api_key\nrevoke_api_key.sync(id=key_id, client=xc.http)" } ] } }, "/v1/public/api-keys/{id}/rotate": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "API keys" ], "summary": "Rotate the signing secret; new secret returned once.", "operationId": "rotateApiKey", "responses": { "200": { "description": "Rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateApiKeyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/api-keys/:id/rotate' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst rotated = await xc.apiKeys.rotateApiKey({ id });\nconsole.log(rotated.secret); // shown ONCE" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.api_keys import rotate_api_key\nrotated = rotate_api_key.sync(id=key_id, client=xc.http)" } ] } }, "/v1/public/features/{featureId}/validate": { "parameters": [ { "in": "path", "name": "featureId", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Features" ], "summary": "Dry-run validate an options payload.", "description": "Returns `valid: true` with `normalizedOptions` +\n`appliedDefaults[]`, or `valid: false` with structured\n`errors[]`. Always HTTP 200 regardless of validation\noutcome per §5.2.7.\n", "operationId": "validateFeatureOptions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateFeatureRequest" } } } }, "responses": { "200": { "description": "Validation result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateFeatureResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/features/:featureId/validate' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst result = await xc.features.validateFeatureOptions({\n id: 'convert-mp3-to-aac',\n requestBody: { options: { bitrate: 192 } },\n});" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.features import validate_feature_options\nfrom xconvert.v1.generated.models.validate_feature_request import ValidateFeatureRequest\nresult = validate_feature_options.sync(\n id=\"convert-mp3-to-aac\", client=xc.http,\n body=ValidateFeatureRequest(options={\"bitrate\": 192}),\n)" } ] } }, "/v1/public/jobs": { "get": { "tags": [ "Jobs" ], "summary": "List the caller's jobs with keyset pagination.", "operationId": "listJobs", "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "queued", "processing", "complete", "failed", "canceled" ] } }, { "in": "query", "name": "createdAfter", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "createdBefore", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Page of jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobListResponse" } } } }, "400": { "$ref": "#/components/responses/Problem" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/v1/public/jobs' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst page = await xc.jobs.listJobs({ limit: 20 });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.jobs import list_jobs\npage = list_jobs.sync(client=xc.http, limit=20)" } ] }, "post": { "tags": [ "Jobs" ], "summary": "Submit a conversion job.", "operationId": "createJob", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } } }, "responses": { "202": { "description": "Job accepted (async).", "headers": { "x-request-id": { "$ref": "#/components/headers/XRequestId" }, "x-xconvert-api-version": { "$ref": "#/components/headers/XXconvertApiVersion" }, "x-xconvert-credits-used": { "$ref": "#/components/headers/XXconvertCreditsUsed" }, "x-xconvert-credits-remaining": { "$ref": "#/components/headers/XXconvertCreditsRemaining" }, "x-xconvert-idempotent-replayed": { "description": "`true` if this is a cached idempotent replay (§5.3.6).", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/InternalError" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/jobs' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst job = await xc.submitJob({\n featureId: 'convert-mp3-to-aac',\n fileIds: [uploadedFileId],\n fromType: 'mp3',\n toType: 'aac',\n processType: 'convert',\n options: {}, // server applies feature baselines + defaults\n});\n\nconst final = await xc.pollUntilDone(job.id);\nconsole.log(final.outputs?.[0]?.downloadUrl);\n " }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.models.create_job_request import CreateJobRequest\njob = xc.submit_job(CreateJobRequest(\n feature_id=\"convert-mp3-to-aac\",\n file_ids=[uploaded_file_id],\n from_type=\"mp3\",\n to_type=\"aac\",\n process_type=\"convert\",\n))\n\nfinal = xc.poll_until_done(job.id)\nprint(final.outputs[0].download_url)\n " } ] } }, "/v1/public/jobs/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Jobs" ], "summary": "Get a single job with strong ETag.", "operationId": "getJob", "parameters": [ { "in": "header", "name": "If-None-Match", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job detail.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "304": { "description": "Not Modified; ETag matches.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/v1/public/jobs/:id' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst job = await xc.getJob(id);" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\njob = xc.get_job(id)" } ] }, "delete": { "tags": [ "Jobs" ], "summary": "Cancel a PENDING job (soft, row retained).", "operationId": "cancelJob", "responses": { "200": { "description": "Canceled or already-terminal state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X DELETE 'https://api.xconvert.com/v1/public/jobs/:id' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nawait xc.jobs.cancelJob({ id });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.jobs import cancel_job\ncancel_job.sync(id=job_id, client=xc.http)" } ] } }, "/v1/public/uploads": { "post": { "tags": [ "Uploads" ], "summary": "Create an upload session.", "operationId": "createUpload", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadRequest" } } } }, "responses": { "200": { "description": "Signed handoffs per file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/uploads' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst upload = await xc.uploads.createUpload({\n requestBody: {\n featureId: 'convert-mp3-to-aac',\n files: [{ name: 'song.mp3', sizeBytes: 4_500_000, contentType: 'audio/mpeg' }],\n },\n});\n// PUT your bytes to upload.uploads[0].chunkEndpoint with Content-Range." }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.uploads import create_upload\nfrom xconvert.v1.generated.models.create_upload_request import CreateUploadRequest\nfrom xconvert.v1.generated.models.upload_file_request import UploadFileRequest\nupload = create_upload.sync(\n client=xc.http,\n body=CreateUploadRequest(\n feature_id=\"convert-mp3-to-aac\",\n files=[UploadFileRequest(name=\"song.mp3\", size_bytes=4_500_000, content_type=\"audio/mpeg\")],\n ),\n)" } ] } }, "/v1/public/uploads/{uploadId}/complete": { "parameters": [ { "in": "path", "name": "uploadId", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Uploads" ], "summary": "Finalize the session; returns canonical fileIds.", "operationId": "completeUpload", "responses": { "200": { "description": "Complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteUploadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/uploads/:uploadId/complete' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst done = await xc.uploads.completeUpload({ uploadId });\nconst fileId = done.files[0].fileId;" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.uploads import complete_upload\ndone = complete_upload.sync(client=xc.http, upload_id=upload_id)\nfile_id = done.files[0].file_id" } ] } }, "/v1/public/uploads/{uploadId}": { "parameters": [ { "in": "path", "name": "uploadId", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "Uploads" ], "summary": "Cancel a pending upload session.", "operationId": "cancelUpload", "responses": { "200": { "description": "Canceled or already-terminal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteUploadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X DELETE 'https://api.xconvert.com/v1/public/uploads/:uploadId' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nawait xc.uploads.cancelUpload({ uploadId });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.uploads import cancel_upload\ncancel_upload.sync(client=xc.http, upload_id=upload_id)" } ] } }, "/v1/public/webhook-endpoints": { "get": { "tags": [ "Webhooks (customer)" ], "summary": "List webhook endpoints.", "operationId": "listWebhookEndpoints", "parameters": [ { "in": "query", "name": "includeStopped", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Endpoints.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/v1/public/webhook-endpoints' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst endpoints = await xc.webhooks.listWebhookEndpoints({});" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.webhooks_customer import list_webhook_endpoints\nendpoints = list_webhook_endpoints.sync(client=xc.http)" } ] }, "post": { "tags": [ "Webhooks (customer)" ], "summary": "Register a new account-level webhook endpoint.", "operationId": "createWebhookEndpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "Created. Secret returned once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/webhook-endpoints' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst endpoint = await xc.webhooks.createWebhookEndpoint({\n requestBody: { url: 'https://yoursite.com/hooks/xconvert', events: ['job.completed'] },\n});" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.webhooks_customer import create_webhook_endpoint\nfrom xconvert.v1.generated.models.create_webhook_endpoint_request import CreateWebhookEndpointRequest\nendpoint = create_webhook_endpoint.sync(\n client=xc.http,\n body=CreateWebhookEndpointRequest(url=\"https://yoursite.com/hooks/xconvert\", events=[\"job.completed\"]),\n)" } ] } }, "/v1/public/webhook-endpoints/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "Webhooks (customer)" ], "summary": "Get a single endpoint (never returns the secret).", "operationId": "getWebhookEndpoint", "responses": { "200": { "description": "Endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/v1/public/webhook-endpoints/:id' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst endpoint = await xc.webhooks.getWebhookEndpoint({ id });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.webhooks_customer import get_webhook_endpoint\nendpoint = get_webhook_endpoint.sync(id=endpoint_id, client=xc.http)" } ] }, "patch": { "tags": [ "Webhooks (customer)" ], "summary": "Partial update (url, enabledEvents, description, maxConcurrentDeliveries).", "operationId": "patchWebhookEndpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "Updated endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X PATCH 'https://api.xconvert.com/v1/public/webhook-endpoints/:id' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst updated = await xc.webhooks.patchWebhookEndpoint({ id, requestBody: { events: [...] } });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.webhooks_customer import patch_webhook_endpoint\n# see the spec for PatchWebhookEndpointRequest fields" } ] }, "delete": { "tags": [ "Webhooks (customer)" ], "summary": "Soft stop. Transitions to `stopped_by_user`.", "operationId": "stopWebhookEndpoint", "responses": { "200": { "description": "Stopped or already-stopped state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X DELETE 'https://api.xconvert.com/v1/public/webhook-endpoints/:id' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nawait xc.webhooks.stopWebhookEndpoint({ id });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.webhooks_customer import stop_webhook_endpoint\nstop_webhook_endpoint.sync(id=endpoint_id, client=xc.http)" } ] } }, "/v1/public/webhook-endpoints/{id}/resume": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks (customer)" ], "summary": "Transition `stopped_by_user` -> `active`.", "operationId": "resumeWebhookEndpoint", "responses": { "200": { "description": "Resumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/webhook-endpoints/:id/resume' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nawait xc.webhooks.resumeWebhookEndpoint({ id });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.webhooks_customer import resume_webhook_endpoint\nresume_webhook_endpoint.sync(id=endpoint_id, client=xc.http)" } ] } }, "/v1/public/webhook-endpoints/{id}/acknowledge-secret": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks (customer)" ], "summary": "Transition `pending_secret_ack` -> `active`.", "operationId": "acknowledgeWebhookSecret", "responses": { "200": { "description": "Acknowledged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/webhook-endpoints/:id/acknowledge-secret' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nawait xc.webhooks.acknowledgeWebhookSecret({ id });" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.webhooks_customer import acknowledge_webhook_secret\nacknowledge_webhook_secret.sync(id=endpoint_id, client=xc.http)" } ] } }, "/v1/public/webhook-endpoints/{id}/rotate-secret": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks (customer)" ], "summary": "Customer-initiated rotate with 24h overlap.", "operationId": "rotateWebhookSecret", "responses": { "200": { "description": "Rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateSecretResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/v1/public/webhook-endpoints/:id/rotate-secret' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst rotated = await xc.webhooks.rotateWebhookSecret({ id });\nconsole.log(rotated.secret); // shown ONCE" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.webhooks_customer import rotate_webhook_secret\nrotated = rotate_webhook_secret.sync(id=endpoint_id, client=xc.http)" } ] } }, "/admin/webhook-endpoints/{id}/pause": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks (admin)" ], "summary": "Admin pause; any state except `disabled` -> `paused_by_admin`.", "operationId": "adminPauseWebhookEndpoint", "responses": { "200": { "description": "Paused or already-paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/webhook-endpoints/:id/pause' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/webhook-endpoints/{id}/unpause": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks (admin)" ], "summary": "Admin unpause; `paused_by_admin` -> `active`.", "operationId": "adminUnpauseWebhookEndpoint", "responses": { "200": { "description": "Unpaused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/webhook-endpoints/:id/unpause' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/webhook-endpoints/{id}/force-rotate": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks (admin)" ], "summary": "Zero-overlap secret rotation; status flips to `pending_secret_ack` unless paused.", "operationId": "adminForceRotateWebhookSecret", "responses": { "200": { "description": "Rotated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateSecretResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/webhook-endpoints/:id/force-rotate' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/credits/refund": { "post": { "tags": [ "Admin credits" ], "summary": "Per-workflow credit refund (v1 stub).", "description": "v1 returns 501 pending Billing V2 per §10.5q.", "operationId": "adminRefund", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditRefundRequest" } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "501": { "$ref": "#/components/responses/NotImplemented" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/credits/refund' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/gdpr/erasure": { "post": { "tags": [ "Admin GDPR" ], "summary": "Regulator-compelled erasure (v1 stub).", "description": "v1 returns 501 pending the erasure pipeline per §10.5q.", "operationId": "adminGdprErasure", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GdprErasureRequest" } } } }, "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "501": { "$ref": "#/components/responses/NotImplemented" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/gdpr/erasure' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/features/schemas/publish": { "post": { "tags": [ "Admin schemas" ], "summary": "xconfig CI batch publish of derived schemas.", "description": "Consumed by xconfig CI only. Shape + semantics owned by §5.2.6.\n", "operationId": "adminPublishFeatureSchemas", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishSchemasRequest" } } } }, "responses": { "200": { "description": "Publish result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishSchemasResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/features/schemas/publish' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/me/billing": { "get": { "tags": [ "Billing" ], "summary": "Billing overview snapshot for the authenticated user.", "description": "Returns the user's live entitlements, per-pool credit balances,\ncombined balance, and `apiBillingEstablished` flag. Reads from\nthe User-doc cache (~1s stale-tolerant) for the hot path; strict\nconsistency callers query DAOs directly. Per §F11.\n", "operationId": "meBillingOverview", "responses": { "200": { "description": "Overview payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingOverview" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/me/billing' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst overview = await xc.billing.meBillingOverview();" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.billing import me_billing_overview\noverview = me_billing_overview.sync(client=xc.http)" } ] } }, "/me/billing/history": { "get": { "tags": [ "Billing" ], "summary": "Paginated payment events for the authenticated user.", "operationId": "meBillingHistory", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "skip", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional filter to one PaymentEventType value. Invalid values\nare silently ignored (no 400) — defensive against client\ncache drift on enum names.\n" } ], "responses": { "200": { "description": "Paginated payment_events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingHistoryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/me/billing/history' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" } ] } }, "/me/billing/usage": { "get": { "tags": [ "Billing" ], "summary": "Debit aggregations over a date window (default last 30 days).", "operationId": "meBillingUsage", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Aggregations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingUsageResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/me/billing/usage' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" }, { "lang": "TypeScript", "label": "@xconvert/sdk", "source": "// npm install @xconvert/sdk\nimport { Xconvert } from '@xconvert/sdk/v1';\nconst xc = new Xconvert({ apiKey: process.env.XCONVERT_API_KEY! });\n\nconst usage = await xc.billing.meBillingUsage({});" }, { "lang": "Python", "label": "xconvert", "source": "# pip install xconvert\nimport os\nfrom xconvert.v1 import Xconvert, ClientOptions\nxc = Xconvert(ClientOptions(api_key=os.environ[\"XCONVERT_API_KEY\"]))\n\nfrom xconvert.v1.generated.api.billing import me_billing_usage\nusage = me_billing_usage.sync(client=xc.http)" } ] } }, "/me/billing/grants": { "get": { "tags": [ "Billing" ], "summary": "Grant history for the authenticated user.", "operationId": "meBillingGrants", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 } } ], "responses": { "200": { "description": "Grant list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingGrantsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/me/billing/grants' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" } ] } }, "/me/billing/export.json": { "get": { "tags": [ "Billing" ], "summary": "Bulk JSON export — events + grants for the authenticated user.", "description": "Capped at 5000 rows per kind. Optional `since` / `until` filter on\nevents. Per §F11 audit / compliance use case.\n", "operationId": "meBillingExportJson", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Export bundle.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingExport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/me/billing/export.json' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" } ] } }, "/me/billing/export.csv": { "get": { "tags": [ "Billing" ], "summary": "CSV export — payment events only, single-table format.", "description": "RFC 4180 minimal quoting. Newlines in description fields are\nreplaced with spaces (single-line cells). Header row + one row\nper event.\n", "operationId": "meBillingExportCsv", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "CSV body.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/me/billing/export.csv' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" } ] } }, "/me/billing/topup": { "post": { "tags": [ "Billing" ], "summary": "Start a credit-pack top-up via Stripe Checkout.", "description": "Returns a Stripe-hosted Checkout URL. Webhook fulfilment writes\nthe resulting CreditGrant when session.completed arrives. Per §F12.\n", "operationId": "meBillingTopup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupRequest" } } } }, "responses": { "200": { "description": "Checkout URL + pack metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/me/billing/topup' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/me/billing/topup/packs": { "get": { "tags": [ "Billing" ], "summary": "Available credit packs for top-up.", "operationId": "meBillingTopupPacks", "responses": { "200": { "description": "Pack catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupPacksResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/me/billing/topup/packs' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" } ] } }, "/me/billing/api-subscription": { "post": { "tags": [ "Billing" ], "summary": "Start an API subscription via Stripe Checkout (recurring).", "description": "Stripe-only per §F2 (PayPal does not handle metered/variable-balance).\nReturns 409 if the user already has an active API subscription\n(§F2 invariant). Per §F2 + §7.1.\n", "operationId": "meBillingApiSubscriptionStart", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSubscriptionRequest" } } } }, "responses": { "200": { "description": "Checkout URL + plan metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSubscriptionResponse" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "User already has an active API subscription.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/me/billing/api-subscription' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/me/billing/api-subscription/plans": { "get": { "tags": [ "Billing" ], "summary": "Available API subscription plans.", "operationId": "meBillingApiSubscriptionPlans", "responses": { "200": { "description": "Plan catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSubscriptionPlansResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/me/billing/api-subscription/plans' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" } ] } }, "/me/billing/api-subscription/cancel": { "post": { "tags": [ "Billing" ], "summary": "Cancel the user's active API subscription at period end (§F19).", "description": "Idempotent: returns the same shape whether or not there's an\nactive sub. The user keeps API access until `currentPeriodEnd`;\nthe expiry-sweep cron transitions to EXPIRED at that point.\n", "operationId": "meBillingApiSubscriptionCancel", "responses": { "200": { "description": "Cancel result with status code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSubscriptionCancelResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/me/billing/api-subscription/cancel' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/users/{userId}/billing": { "get": { "tags": [ "Admin billing" ], "summary": "Admin overview of one user's billing state.", "operationId": "adminBillingOverview", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Admin-shaped overview (entitlements, recent events, grants).", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X GET 'https://api.xconvert.com/admin/users/:userId/billing' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY'" } ] } }, "/admin/users/{userId}/billing/grant-entitlement": { "post": { "tags": [ "Admin billing" ], "summary": "Manually grant an entitlement to a user.", "operationId": "adminBillingGrantEntitlement", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminGrantEntitlementRequest" } } } }, "responses": { "200": { "description": "Grant result.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/users/:userId/billing/grant-entitlement' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/users/{userId}/billing/revoke-entitlement": { "post": { "tags": [ "Admin billing" ], "summary": "Revoke (markExpired) a user's live entitlement.", "operationId": "adminBillingRevokeEntitlement", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRevokeEntitlementRequest" } } } }, "responses": { "200": { "description": "Revoke result.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/users/:userId/billing/revoke-entitlement' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/users/{userId}/billing/grant-credits": { "post": { "tags": [ "Admin billing" ], "summary": "Grant credits to a user (ADMIN_PROMO grant).", "operationId": "adminBillingGrantCredits", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminGrantCreditsRequest" } } } }, "responses": { "200": { "description": "Grant result with grantId.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/users/:userId/billing/grant-credits' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/billing/grant-bulk": { "post": { "tags": [ "Admin billing" ], "summary": "Bulk-grant credits to a list of users (one bulkGrantId tags all).", "operationId": "adminBillingGrantBulk", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminBulkGrantRequest" } } } }, "responses": { "200": { "description": "Bulk result with succeeded[] and failed[] lists.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/billing/grant-bulk' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } }, "/admin/billing/validate/{userId}": { "post": { "tags": [ "Admin billing" ], "summary": "Run an on-demand drift check for one user (§21.1).", "description": "Same per-user check the BillingValidationCron runs hourly.\nRead-only — does not auto-repair drift.\n", "operationId": "adminBillingValidate", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Drift result with classified anomalies.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST 'https://api.xconvert.com/admin/billing/validate/:userId' \\\n -H 'Authorization: Bearer $XCONVERT_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{ ... }'" } ] } } } }