{"openapi":"3.1.0","info":{"title":"Tolldeck API","version":"1.0.0","description":"Stable error codes: key_missing, key_invalid, key_revoked, key_expired, ip_not_allowed, operation_not_in_plan, rate_limited, quota_exceeded, subscription_inactive, developer_suspended, app_suspended, upstream_timeout, upstream_error, upstream_unsafe, payload_too_large, spec_invalid, spec_external_ref, signature_invalid, batch_replayed, approval_required, limit_reached, feature_not_in_plan, tenant_suspended, unsafe_url, bad_request, not_found, validation_failed. Errors use { error: { code, message, details } }."},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"n3k_…"}}},"paths":{"/edge/verify":{"post":{"summary":"Verify an API key for the provider's own gateway (X-Tolldeck-Product + X-Tolldeck-Signature: t=..,v1=..)","tags":["Edge"],"security":[],"x-scope":"public","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"key":{"type":"string"},"operation":{"type":"string"},"ip":{"type":"string"},"reserve":{"type":"boolean"},"nonce":{"type":"string"}},"required":["key"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"valid":{"type":"boolean"},"code":{"type":"string"},"remaining":{"type":["number","null"]},"rate":{"anyOf":[{"type":"object","properties":{"limit":{"type":"number"},"remaining":{"type":"number"},"reset":{"type":"number"}},"required":["limit","remaining","reset"],"additionalProperties":false},{"type":"null"}]}},"required":["valid","code","remaining","rate"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/edge/usage":{"post":{"summary":"Report a usage batch (idempotent by batch_id, at most 5,000 items, items older than 48 h are rejected)","tags":["Edge"],"security":[],"x-scope":"public","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"batch_id":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"operation":{"type":"string"},"status":{"type":"number"},"at":{"type":["string","number"]},"latency_ms":{"type":"number"},"reserved":{"type":"boolean"}},"required":["key","status","at"],"additionalProperties":false}}},"required":["batch_id","items"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean"},"duplicate":{"type":"boolean"}},"required":["ok","duplicate"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/me":{"get":{"summary":"The workspace this key belongs to","tags":["Workspace"],"security":[{"bearer":[]}],"x-scope":"read","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"members":{"type":"number"}},"required":["id","name","plan","members"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/products":{"get":{"summary":"List API products","tags":["Products"],"security":[{"bearer":[]}],"x-scope":"products:read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","live","deprecated","archived"]}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}},"required":["total","data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create an API product (an edge-mode product returns its edge secret once)","tags":["Products"],"security":[{"bearer":[]}],"x-scope":"products:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"slug":{"type":"string","maxLength":48},"description":{"type":"string","maxLength":2000},"mode":{"type":"string","enum":["gateway","edge"]},"base_path":{"type":"string","maxLength":100},"visibility":{"type":"string","enum":["public","partner","private"]},"upstream":{"type":"object","properties":{"base_url":{"type":"string","maxLength":500},"timeout_ms":{"type":"integer","minimum":1000,"maximum":120000},"auth_kind":{"type":"string","enum":["none","header","basic","bearer"]},"auth_header_name":{"type":"string","maxLength":60},"secret":{"type":"string","maxLength":500},"forward_headers":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":60}}},"additionalProperties":false},"key_header":{"type":"string","pattern":"^[A-Za-z0-9-]{1,40}$"},"key_query":{"type":"boolean"},"cors_origins":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},"sandbox":{"type":"object","properties":{"mock":{"type":"boolean"},"base_url":{"type":"string","maxLength":500}},"additionalProperties":false}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/products/{id}":{"get":{"summary":"Get an API product (secrets are never returned)","tags":["Products"],"security":[{"bearer":[]}],"x-scope":"products:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"patch":{"summary":"Update settings, upstream, CORS, sandbox or status (live needs an upstream and a published spec)","tags":["Products"],"security":[{"bearer":[]}],"x-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":2000},"status":{"type":"string","enum":["draft","live","deprecated","archived"]},"visibility":{"type":"string","enum":["public","partner","private"]},"base_path":{"type":"string","maxLength":100},"key_header":{"type":"string","pattern":"^[A-Za-z0-9-]{1,40}$"},"key_query":{"type":"boolean"},"cors_origins":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":200}},"upstream":{"type":"object","properties":{"base_url":{"type":"string","maxLength":500},"timeout_ms":{"type":"integer","minimum":1000,"maximum":120000},"auth_kind":{"type":"string","enum":["none","header","basic","bearer"]},"auth_header_name":{"type":"string","maxLength":60},"secret":{"type":"string","maxLength":500},"forward_headers":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":60}}},"additionalProperties":false},"sandbox":{"type":"object","properties":{"mock":{"type":"boolean"},"base_url":{"type":"string","maxLength":500}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"delete":{"summary":"Delete a product (archived instead when developers subscribed)","tags":["Products"],"security":[{"bearer":[]}],"x-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"required":["archived","deleted"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/products/{id}/rotate-edge-secret":{"post":{"summary":"Generate a new edge secret (returned once; the old one stops working)","tags":["Products"],"security":[{"bearer":[]}],"x-scope":"products:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"secret":{"type":"string"}},"required":["secret"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/products/{id}/specs":{"get":{"summary":"List spec versions of a product","tags":["Docs"],"security":[{"bearer":[]}],"x-scope":"docs:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Import an OpenAPI/Swagger spec (multipart file= or JSON {content}); external $refs are refused","tags":["Docs"],"security":[{"bearer":[]}],"x-scope":"docs:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"content":{"type":"string"},"version":{"type":"string","maxLength":40}},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/specs/{id}":{"get":{"summary":"Spec version with its dereferenced document (?document=1)","tags":["Docs"],"security":[{"bearer":[]}],"x-scope":"docs:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"document","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"patch":{"summary":"Publish, make default, deprecate (with sunset date), retire, or set operation weights","tags":["Docs"],"security":[{"bearer":[]}],"x-scope":"docs:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string","enum":["publish","deprecate","retire","weights"]},"make_default":{"type":"boolean"},"sunset_at":{"type":["string","null"]},"weights":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number","minimum":0,"maximum":100000}}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"delete":{"summary":"Delete a draft spec version","tags":["Docs"],"security":[{"bearer":[]}],"x-scope":"docs:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/plans":{"get":{"summary":"List usage plans","tags":["Plans"],"security":[{"bearer":[]}],"x-scope":"plans:read","parameters":[{"name":"product_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}},"required":["total","data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Create a usage plan (prices in minor units)","tags":["Plans"],"security":[{"bearer":[]}],"x-scope":"plans:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"product_id":{"type":"string","pattern":"^[0-9a-f]{24}$"},"name":{"type":"string","minLength":1,"maxLength":120},"slug":{"type":"string","maxLength":40},"public":{"type":"boolean"},"price_month":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","minLength":3,"maxLength":3},"included_units":{"type":"integer","minimum":0,"maximum":9007199254740991},"unit":{"type":"string","enum":["request","weighted_unit"]},"overage_per_block":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_size":{"type":"integer","minimum":1,"maximum":9007199254740991},"hard_cap":{"type":"boolean"},"rate":{"type":"object","properties":{"per_second":{"type":"number","minimum":0.1},"burst":{"type":"number","minimum":1}},"additionalProperties":false},"trial_days":{"type":"integer","minimum":0,"maximum":9007199254740991},"approval_required":{"type":"boolean"},"operation_allowlist":{"maxItems":500,"type":"array","items":{"type":"string","maxLength":120}},"bill_upstream_errors":{"type":"boolean"},"log_sample_pct":{"type":"number","minimum":0,"maximum":100},"body_cap_mb":{"type":"number","minimum":0.001,"maximum":100}},"required":["product_id","name"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/plans/{id}":{"patch":{"summary":"Edit a plan: limits apply to existing subscriptions at once","tags":["Plans"],"security":[{"bearer":[]}],"x-scope":"plans:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"slug":{"type":"string","maxLength":40},"public":{"type":"boolean"},"price_month":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"type":"string","minLength":3,"maxLength":3},"included_units":{"type":"integer","minimum":0,"maximum":9007199254740991},"unit":{"type":"string","enum":["request","weighted_unit"]},"overage_per_block":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_size":{"type":"integer","minimum":1,"maximum":9007199254740991},"hard_cap":{"type":"boolean"},"rate":{"type":"object","properties":{"per_second":{"type":"number","minimum":0.1},"burst":{"type":"number","minimum":1}},"additionalProperties":false},"trial_days":{"type":"integer","minimum":0,"maximum":9007199254740991},"approval_required":{"type":"boolean"},"operation_allowlist":{"maxItems":500,"type":"array","items":{"type":"string","maxLength":120}},"bill_upstream_errors":{"type":"boolean"},"log_sample_pct":{"type":"number","minimum":0,"maximum":100},"body_cap_mb":{"type":"number","minimum":0.001,"maximum":100},"status":{"type":"string","enum":["active","archived"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"delete":{"summary":"Delete a plan (archived instead when subscriptions use it)","tags":["Plans"],"security":[{"bearer":[]}],"x-scope":"plans:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"archived":{"type":"boolean"},"deleted":{"type":"boolean"}},"required":["archived","deleted"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/developers":{"get":{"summary":"List developers (status, e-mail search)","tags":["Developers"],"security":[{"bearer":[]}],"x-scope":"developers:read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"email","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}},"required":["total","data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Invite a developer (active, no self sign-up)","tags":["Developers"],"security":[{"bearer":[]}],"x-scope":"developers:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"type":"string","maxLength":200},"company":{"type":"string","maxLength":200},"country":{"type":"string","minLength":2,"maxLength":2}},"required":["email"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/developers/{id}":{"patch":{"summary":"Approve, suspend or reinstate a developer","tags":["Developers"],"security":[{"bearer":[]}],"x-scope":"developers:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string","enum":["approve","suspend","reinstate"]}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/apps":{"get":{"summary":"List apps","tags":["Apps"],"security":[{"bearer":[]}],"x-scope":"developers:read","parameters":[{"name":"developer_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}},"required":["total","data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/apps/{id}":{"patch":{"summary":"Suspend or reactivate an app, edit its IP allow-list","tags":["Apps"],"security":[{"bearer":[]}],"x-scope":"developers:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["active","suspended"]},"ip_allowlist":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":64}},"name":{"type":"string","maxLength":120}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/keys":{"get":{"summary":"List API keys (masked: prefix and last 4 only)","tags":["Keys"],"security":[{"bearer":[]}],"x-scope":"developers:read","parameters":[{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}},"required":["total","data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/keys/{id}/revoke":{"post":{"summary":"Revoke a key at once","tags":["Keys"],"security":[{"bearer":[]}],"x-scope":"developers:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/keys/{id}/rotate":{"post":{"summary":"Rotate a key: the new key is returned once, the old one stays valid for the grace period","tags":["Keys"],"security":[{"bearer":[]}],"x-scope":"developers:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema"}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/subscriptions":{"get":{"summary":"List subscriptions","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"developers:read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"product_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}},"required":["total","data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/subscriptions/{id}":{"patch":{"summary":"Approve a pending subscription, change its plan, or cancel it","tags":["Subscriptions"],"security":[{"bearer":[]}],"x-scope":"developers:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"action":{"type":"string","enum":["approve","change_plan","cancel"]},"plan_id":{"type":"string","pattern":"^[0-9a-f]{24}$"}},"required":["action"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/usage":{"get":{"summary":"Usage rollups (group_by day|product|app|operation|status)","tags":["Usage"],"security":[{"bearer":[]}],"x-scope":"usage:read","parameters":[{"name":"group_by","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"}},{"name":"to","in":"query","required":false,"schema":{"type":"string"}},{"name":"product_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"app_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"env","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices":{"get":{"summary":"List developer usage invoices","tags":["Billing"],"security":[{"bearer":[]}],"x-scope":"billing:read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"developer_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"period","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"total":{"type":"number"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}},"required":["total","data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices/{id}":{"get":{"summary":"Invoice with lines","tags":["Billing"],"security":[{"bearer":[]}],"x-scope":"billing:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/invoices/{id}/refund":{"post":{"summary":"Refund up to the paid amount (minor units)","tags":["Billing"],"security":[{"bearer":[]}],"x-scope":"billing:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"reason":{"type":"string","maxLength":300}},"required":["amount"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/webhooks":{"get":{"summary":"List outbound webhook endpoints","tags":["Webhooks"],"security":[{"bearer":[]}],"x-scope":"webhooks","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}},"required":["id","url","events"],"additionalProperties":{}}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}},"post":{"summary":"Add an outbound webhook endpoint (secret returned once)","tags":["Webhooks"],"security":[{"bearer":[]}],"x-scope":"webhooks","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":500,"format":"uri"},"events":{"maxItems":20,"type":"array","items":{"type":"string"}},"description":{"type":"string","maxLength":200}},"required":["url"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"secret":{"type":"string"}},"required":["id","secret"],"additionalProperties":{}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}},"/webhooks/{id}":{"delete":{"summary":"Remove a webhook endpoint","tags":["Webhooks"],"security":[{"bearer":[]}],"x-scope":"webhooks","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"deleted":{"type":"boolean"}},"required":["deleted"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Plan quota exceeded"},"403":{"description":"Key lacks the required scope"},"422":{"description":"Validation failed"},"429":{"description":"Rate limited"}}}}}}