{"openapi":"3.1.0","info":{"title":"LinkCARE — link management","version":"1.0.0","description":"Every operation is also an agent tool with the same name and input (GET /v1/tools, POST /v1/tools/{name}, or MCP at /mcp). Errors carry a stable machine code."},"paths":{"/v1/links":{"post":{"operationId":"links.create","summary":"Create a link. Safe to repeat: the same key and destination return the existing link. The same key with a different destination fails with KEY_TAKEN and never changes the existing link.","x-risk":"write","x-permission":"links:create","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"maxLength":2048,"description":"Where the link sends visitors. http or https.","type":"string"},"domain":{"description":"Hostname or domain id. Default: the organization's default domain.","type":"string"},"key":{"maxLength":128,"description":"Path part of the link. Omit to have one generated. Permanent once created.","type":"string"},"keyLength":{"minimum":4,"maximum":32,"description":"Length of a generated key. Default 7.","type":"integer"},"externalId":{"maxLength":255,"description":"Your own identifier for this link, unique in the organization.","type":"string"},"reuse":{"description":"With no key: return an existing link in service for the same destination.","type":"boolean"},"title":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"description":"ISO time after which the link is gone.","type":"string"},{"type":"null"}]},"expiredTarget":{"anyOf":[{"maxLength":2048,"description":"Where visitors go after expiry. Default: the domain's fallback target.","type":"string"},{"type":"null"}]},"forwardQuery":{"anyOf":[{"description":"Add the visitor's query string to the destination. Null: use the domain's setting.","type":"boolean"},{"type":"null"}]},"redirectStatus":{"anyOf":[{"description":"301, 302, 307 or 308. Null: use the domain's setting.","type":"integer"},{"type":"null"}]},"tags":{"maxItems":20,"type":"array","items":{"maxLength":50,"type":"string"}},"capabilities":{"additionalProperties":false,"description":"Optional behaviors attached to the link.","type":"object","properties":{"targeting":{"anyOf":[{"type":"object","properties":{"ios":{"maxLength":2048,"description":"Destination for iOS devices.","type":"string"},"android":{"maxLength":2048,"description":"Destination for Android devices.","type":"string"},"geo":{"description":"Destination per two-letter country code.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}},{"type":"null"}]},"attribution":{"anyOf":[{"type":"object","properties":{"enabled":{"description":"Accept one extra path segment as a recipient token.","type":"boolean"}},"required":["enabled"]},{"type":"null"}]},"split":{"anyOf":[{"description":"A/B split: two to four destinations with weights adding up to 100. The first is the link's own destination. A visitor keeps the same one for a day. Null removes it.","type":"object","properties":{"variants":{"minItems":2,"maxItems":4,"type":"array","items":{"type":"object","properties":{"destination":{"maxLength":2048,"description":"Where this share of visitors goes.","type":"string"},"weight":{"minimum":1,"maximum":99,"description":"Percent of visitors.","type":"integer"}},"required":["destination","weight"]}}},"required":["variants"]},{"type":"null"}]},"preview":{"anyOf":[{"description":"The card chat and social apps show for the link. Served only to their preview fetchers. Null removes it.","type":"object","properties":{"title":{"maxLength":120,"type":"string"},"description":{"maxLength":240,"type":"string"},"image":{"maxLength":2048,"description":"An https image address. It is referenced, never stored.","type":"string"}}},{"type":"null"}]},"gate":{"anyOf":[{"description":"Ask visitors for a password before the destination. Stored only as a slow hash and never returned: a link reports gate.enabled. Leave out to keep the gate as it is; null removes it.","type":"object","properties":{"password":{"minLength":4,"maxLength":128,"type":"string"}},"required":["password"]},{"type":"null"}]}}},"idempotencyKey":{"minLength":1,"maxLength":128,"description":"Repeat-safe token: the same key and input return the first result.","type":"string"}},"required":["destination"]}}}},"responses":{"201":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"links.list","summary":"List links, newest first. Retired links are left out unless status=retired.","x-risk":"read","x-permission":"links:read","parameters":[{"name":"domain","in":"query","required":false,"schema":{"description":"Domain id or hostname.","type":"string"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"const":"active","type":"string"},{"const":"disabled","type":"string"},{"const":"retired","type":"string"}]}},{"name":"search","in":"query","required":false,"schema":{"maxLength":200,"description":"Matches key, destination or title.","type":"string"}},{"name":"tag","in":"query","required":false,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":200,"default":50,"type":"integer"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/{link}":{"get":{"operationId":"links.get","summary":"Get one link with its click total.","x-risk":"read","x-permission":"links:read","parameters":[{"name":"link","in":"path","required":true,"schema":{"description":"Link id, or the external id you supplied.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"links.edit","summary":"Change a link's settings. Does not change its key (permanent) or destination (use links.repoint).","x-risk":"write","x-permission":"links:edit","parameters":[{"name":"link","in":"path","required":true,"schema":{"description":"Link id, or the external id you supplied.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"description":"ISO time after which the link is gone.","type":"string"},{"type":"null"}]},"expiredTarget":{"anyOf":[{"maxLength":2048,"description":"Where visitors go after expiry. Default: the domain's fallback target.","type":"string"},{"type":"null"}]},"forwardQuery":{"anyOf":[{"description":"Add the visitor's query string to the destination. Null: use the domain's setting.","type":"boolean"},{"type":"null"}]},"redirectStatus":{"anyOf":[{"description":"301, 302, 307 or 308. Null: use the domain's setting.","type":"integer"},{"type":"null"}]},"tags":{"maxItems":20,"type":"array","items":{"maxLength":50,"type":"string"}},"capabilities":{"additionalProperties":false,"description":"Optional behaviors attached to the link.","type":"object","properties":{"targeting":{"anyOf":[{"type":"object","properties":{"ios":{"maxLength":2048,"description":"Destination for iOS devices.","type":"string"},"android":{"maxLength":2048,"description":"Destination for Android devices.","type":"string"},"geo":{"description":"Destination per two-letter country code.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}},{"type":"null"}]},"attribution":{"anyOf":[{"type":"object","properties":{"enabled":{"description":"Accept one extra path segment as a recipient token.","type":"boolean"}},"required":["enabled"]},{"type":"null"}]},"split":{"anyOf":[{"description":"A/B split: two to four destinations with weights adding up to 100. The first is the link's own destination. A visitor keeps the same one for a day. Null removes it.","type":"object","properties":{"variants":{"minItems":2,"maxItems":4,"type":"array","items":{"type":"object","properties":{"destination":{"maxLength":2048,"description":"Where this share of visitors goes.","type":"string"},"weight":{"minimum":1,"maximum":99,"description":"Percent of visitors.","type":"integer"}},"required":["destination","weight"]}}},"required":["variants"]},{"type":"null"}]},"preview":{"anyOf":[{"description":"The card chat and social apps show for the link. Served only to their preview fetchers. Null removes it.","type":"object","properties":{"title":{"maxLength":120,"type":"string"},"description":{"maxLength":240,"type":"string"},"image":{"maxLength":2048,"description":"An https image address. It is referenced, never stored.","type":"string"}}},{"type":"null"}]},"gate":{"anyOf":[{"description":"Ask visitors for a password before the destination. Stored only as a slow hash and never returned: a link reports gate.enabled. Leave out to keep the gate as it is; null removes it.","type":"object","properties":{"password":{"minLength":4,"maxLength":128,"type":"string"}},"required":["password"]},{"type":"null"}]}}},"expectedVersion":{"minimum":0,"description":"Fail with VERSION_CONFLICT unless the record is at this version.","type":"integer"}},"required":[]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/{link}/qr":{"get":{"operationId":"links.qr","summary":"The link's QR code as an SVG file. Scans are recorded as via-QR. Over REST the file itself is returned.","x-risk":"read","x-permission":"links:read","parameters":[{"name":"link","in":"path","required":true,"schema":{"description":"Link id, or the external id you supplied.","type":"string"}},{"name":"level","in":"query","required":false,"schema":{"description":"Error-correction level. Default M.","anyOf":[{"const":"L","type":"string"},{"const":"M","type":"string"},{"const":"Q","type":"string"},{"const":"H","type":"string"}]}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/lookup":{"post":{"operationId":"links.lookup","summary":"Find a link by its domain and key.","x-risk":"read","x-permission":"links:read","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"description":"Domain id or hostname.","type":"string"},"key":{"maxLength":128,"type":"string"}},"required":["key"]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/{link}/repoint":{"post":{"operationId":"links.repoint","summary":"Change where an existing link sends visitors. Printed and shared copies of the link follow.","x-risk":"high","x-permission":"links:repoint","parameters":[{"name":"link","in":"path","required":true,"schema":{"description":"Link id, or the external id you supplied.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"maxLength":2048,"description":"The new destination.","type":"string"},"reason":{"maxLength":500,"type":"string"},"expectedVersion":{"minimum":0,"description":"Fail with VERSION_CONFLICT unless the record is at this version.","type":"integer"}},"required":["destination"]}}}},"responses":{"200":{"description":"Success"},"202":{"description":"A person must approve first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/{link}/disable":{"post":{"operationId":"links.disable","summary":"Stop a link serving visitors for now. Reversible with links.enable.","x-risk":"write","x-permission":"links:edit","parameters":[{"name":"link","in":"path","required":true,"schema":{"description":"Link id, or the external id you supplied.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/{link}/enable":{"post":{"operationId":"links.enable","summary":"Put a disabled link back in service.","x-risk":"write","x-permission":"links:edit","parameters":[{"name":"link","in":"path","required":true,"schema":{"description":"Link id, or the external id you supplied.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/{link}/retire":{"post":{"operationId":"links.retire","summary":"Take a link out of service for good. Its key stays reserved and can never be reused. Not reversible.","x-risk":"high","x-permission":"links:retire","parameters":[{"name":"link","in":"path","required":true,"schema":{"description":"Link id, or the external id you supplied.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"maxLength":500,"type":"string"}},"required":[]}}}},"responses":{"200":{"description":"Success"},"202":{"description":"A person must approve first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/bulk":{"post":{"operationId":"links.bulkCreate","summary":"Create 1 to 100 links. Each is created by the same rules as links.create, in order; the answer has one outcome per item (created, existing, or error with its code). One failed item does not undo the others.","x-risk":"write","x-permission":"links:create","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"links":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"destination":{"maxLength":2048,"description":"Where the link sends visitors. http or https.","type":"string"},"domain":{"description":"Hostname or domain id. Default: the organization's default domain.","type":"string"},"key":{"maxLength":128,"type":"string"},"keyLength":{"minimum":4,"maximum":32,"type":"integer"},"externalId":{"maxLength":255,"type":"string"},"reuse":{"type":"boolean"},"title":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"description":"ISO time after which the link is gone.","type":"string"},{"type":"null"}]},"expiredTarget":{"anyOf":[{"maxLength":2048,"description":"Where visitors go after expiry. Default: the domain's fallback target.","type":"string"},{"type":"null"}]},"forwardQuery":{"anyOf":[{"description":"Add the visitor's query string to the destination. Null: use the domain's setting.","type":"boolean"},{"type":"null"}]},"redirectStatus":{"anyOf":[{"description":"301, 302, 307 or 308. Null: use the domain's setting.","type":"integer"},{"type":"null"}]},"tags":{"maxItems":20,"type":"array","items":{"maxLength":50,"type":"string"}},"capabilities":{"additionalProperties":false,"description":"Optional behaviors attached to the link.","type":"object","properties":{"targeting":{"anyOf":[{"type":"object","properties":{"ios":{"maxLength":2048,"description":"Destination for iOS devices.","type":"string"},"android":{"maxLength":2048,"description":"Destination for Android devices.","type":"string"},"geo":{"description":"Destination per two-letter country code.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}},{"type":"null"}]},"attribution":{"anyOf":[{"type":"object","properties":{"enabled":{"description":"Accept one extra path segment as a recipient token.","type":"boolean"}},"required":["enabled"]},{"type":"null"}]},"split":{"anyOf":[{"description":"A/B split: two to four destinations with weights adding up to 100. The first is the link's own destination. A visitor keeps the same one for a day. Null removes it.","type":"object","properties":{"variants":{"minItems":2,"maxItems":4,"type":"array","items":{"type":"object","properties":{"destination":{"maxLength":2048,"description":"Where this share of visitors goes.","type":"string"},"weight":{"minimum":1,"maximum":99,"description":"Percent of visitors.","type":"integer"}},"required":["destination","weight"]}}},"required":["variants"]},{"type":"null"}]},"preview":{"anyOf":[{"description":"The card chat and social apps show for the link. Served only to their preview fetchers. Null removes it.","type":"object","properties":{"title":{"maxLength":120,"type":"string"},"description":{"maxLength":240,"type":"string"},"image":{"maxLength":2048,"description":"An https image address. It is referenced, never stored.","type":"string"}}},{"type":"null"}]},"gate":{"anyOf":[{"description":"Ask visitors for a password before the destination. Stored only as a slow hash and never returned: a link reports gate.enabled. Leave out to keep the gate as it is; null removes it.","type":"object","properties":{"password":{"minLength":4,"maxLength":128,"type":"string"}},"required":["password"]},{"type":"null"}]}}}},"required":["destination"]}},"idempotencyKey":{"minLength":1,"maxLength":128,"description":"Repeat-safe token: the same key and input return the first result.","type":"string"}},"required":["links"]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/bulk-edit":{"post":{"operationId":"links.bulkEdit","summary":"Make the same settings change on 1 to 100 links, with one outcome per link. Cannot change a destination. More than 25 links at once is a high-risk change.","x-risk":"write","x-permission":"links:edit","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"links":{"minItems":1,"maxItems":100,"type":"array","items":{"description":"Link id, or the external id you supplied.","type":"string"}},"changes":{"additionalProperties":false,"type":"object","properties":{"title":{"anyOf":[{"maxLength":256,"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"description":"ISO time after which the link is gone.","type":"string"},{"type":"null"}]},"expiredTarget":{"anyOf":[{"maxLength":2048,"description":"Where visitors go after expiry. Default: the domain's fallback target.","type":"string"},{"type":"null"}]},"forwardQuery":{"anyOf":[{"description":"Add the visitor's query string to the destination. Null: use the domain's setting.","type":"boolean"},{"type":"null"}]},"redirectStatus":{"anyOf":[{"description":"301, 302, 307 or 308. Null: use the domain's setting.","type":"integer"},{"type":"null"}]},"tags":{"maxItems":20,"type":"array","items":{"maxLength":50,"type":"string"}},"capabilities":{"additionalProperties":false,"description":"Optional behaviors attached to the link.","type":"object","properties":{"targeting":{"anyOf":[{"type":"object","properties":{"ios":{"maxLength":2048,"description":"Destination for iOS devices.","type":"string"},"android":{"maxLength":2048,"description":"Destination for Android devices.","type":"string"},"geo":{"description":"Destination per two-letter country code.","type":"object","patternProperties":{"^(.*)$":{"type":"string"}}}}},{"type":"null"}]},"attribution":{"anyOf":[{"type":"object","properties":{"enabled":{"description":"Accept one extra path segment as a recipient token.","type":"boolean"}},"required":["enabled"]},{"type":"null"}]},"split":{"anyOf":[{"description":"A/B split: two to four destinations with weights adding up to 100. The first is the link's own destination. A visitor keeps the same one for a day. Null removes it.","type":"object","properties":{"variants":{"minItems":2,"maxItems":4,"type":"array","items":{"type":"object","properties":{"destination":{"maxLength":2048,"description":"Where this share of visitors goes.","type":"string"},"weight":{"minimum":1,"maximum":99,"description":"Percent of visitors.","type":"integer"}},"required":["destination","weight"]}}},"required":["variants"]},{"type":"null"}]},"preview":{"anyOf":[{"description":"The card chat and social apps show for the link. Served only to their preview fetchers. Null removes it.","type":"object","properties":{"title":{"maxLength":120,"type":"string"},"description":{"maxLength":240,"type":"string"},"image":{"maxLength":2048,"description":"An https image address. It is referenced, never stored.","type":"string"}}},{"type":"null"}]}}}}}},"required":["links","changes"]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/links/bulk-retire":{"post":{"operationId":"links.bulkRetire","summary":"Retire 1 to 100 links for good, with one outcome per link. Their keys stay reserved. Not reversible.","x-risk":"high","x-permission":"links:retire","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"links":{"minItems":1,"maxItems":100,"type":"array","items":{"description":"Link id, or the external id you supplied.","type":"string"}},"reason":{"maxLength":500,"type":"string"}},"required":["links"]}}}},"responses":{"200":{"description":"Success"},"202":{"description":"A person must approve first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/resolve":{"post":{"operationId":"links.explain","summary":"Dry run: what a visitor would get for a short URL, and which step of the resolution procedure decided it. Records nothing.","x-risk":"read","x-permission":"links:read","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"maxLength":2048,"description":"A full short URL, e.g. https://jom.care/abc?x=1.","type":"string"},"country":{"minLength":2,"maxLength":2,"type":"string"},"os":{"anyOf":[{"const":"ios","type":"string"},{"const":"android","type":"string"},{"const":"other","type":"string"}]},"bot":{"type":"boolean"},"previewFetcher":{"description":"As a chat or social app's preview fetcher would see it.","type":"boolean"},"bucket":{"minimum":0,"maximum":99,"description":"Which hundredth of visitors, for an A/B split.","type":"integer"},"gatePassed":{"description":"As a visitor who has given the right password would see it.","type":"boolean"},"at":{"description":"ISO time to evaluate expiry at. Default: now.","type":"string"}},"required":["url"]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains":{"get":{"operationId":"domains.list","summary":"List the organization's domains with their root and fallback targets.","x-risk":"read","x-permission":"domains:read","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"domains.add","summary":"Register a hostname for the organization. Safe to repeat.","x-risk":"write","x-permission":"domains:manage","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hostname":{"maxLength":253,"type":"string"},"rootTarget":{"anyOf":[{"maxLength":2048,"description":"Where a visitor to the bare domain is sent.","type":"string"},{"type":"null"}]},"fallbackTarget":{"anyOf":[{"maxLength":2048,"description":"Where a visitor is sent when no link in service matches.","type":"string"},{"type":"null"}]},"settings":{"additionalProperties":false,"type":"object","properties":{"caseSensitive":{"description":"Default true.","type":"boolean"},"redirectStatus":{"description":"301, 302, 307 or 308. Default 302.","type":"integer"},"forwardQuery":{"description":"Default true.","type":"boolean"}}},"isDefault":{"type":"boolean"}},"required":["hostname"]}}}},"responses":{"201":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{domain}":{"get":{"operationId":"domains.get","summary":"Get one domain.","x-risk":"read","x-permission":"domains:read","parameters":[{"name":"domain","in":"path","required":true,"schema":{"description":"Domain id or hostname.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"domains.update","summary":"Change a domain's root target, fallback target or settings. Affects every visitor to the domain.","x-risk":"high","x-permission":"domains:manage","parameters":[{"name":"domain","in":"path","required":true,"schema":{"description":"Domain id or hostname.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rootTarget":{"anyOf":[{"maxLength":2048,"description":"Null clears it.","type":"string"},{"type":"null"}]},"fallbackTarget":{"anyOf":[{"maxLength":2048,"description":"Null clears it.","type":"string"},{"type":"null"}]},"settings":{"additionalProperties":false,"type":"object","properties":{"caseSensitive":{"description":"Default true.","type":"boolean"},"redirectStatus":{"description":"301, 302, 307 or 308. Default 302.","type":"integer"},"forwardQuery":{"description":"Default true.","type":"boolean"}}},"isDefault":{"type":"boolean"},"expectedVersion":{"minimum":0,"description":"Fail with VERSION_CONFLICT unless the record is at this version.","type":"integer"}},"required":[]}}}},"responses":{"200":{"description":"Success"},"202":{"description":"A person must approve first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"domains.remove","summary":"Take a domain out of service. Refused while it has links that are not retired.","x-risk":"high","x-permission":"domains:manage","parameters":[{"name":"domain","in":"path","required":true,"schema":{"description":"Domain id or hostname.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"202":{"description":"A person must approve first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{domain}/check":{"post":{"operationId":"domains.check","summary":"Check from the public internet whether the hostname reaches this service, and mark the domain verified when it does. Safe to repeat.","x-risk":"write","x-permission":"domains:manage","parameters":[{"name":"domain","in":"path","required":true,"schema":{"description":"Domain id or hostname.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{domain}/share":{"post":{"operationId":"domains.share","summary":"Let another organization create links on a domain you own, optionally holding its keys to prefixes. Sharing again replaces the prefixes.","x-risk":"write","x-permission":"domains:manage","parameters":[{"name":"domain","in":"path","required":true,"schema":{"description":"Domain id or hostname.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"description":"Organization id or slug.","type":"string"},"keyPrefixes":{"maxItems":20,"type":"array","items":{"maxLength":32,"type":"string"}}},"required":["organization"]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/domains/{domain}/unshare":{"post":{"operationId":"domains.unshare","summary":"Stop another organization creating links on your domain. Its existing links keep working.","x-risk":"write","x-permission":"domains:manage","parameters":[{"name":"domain","in":"path","required":true,"schema":{"description":"Domain id or hostname.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"description":"Organization id or slug.","type":"string"}},"required":["organization"]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analytics":{"get":{"operationId":"analytics.summary","summary":"Click totals, time series, breakdowns and top links for the organization or one link.","x-risk":"read","x-permission":"analytics:read","parameters":[{"name":"linkId","in":"query","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"description":"ISO time. Default: 30 days before `to`.","type":"string"}},{"name":"to","in":"query","required":false,"schema":{"description":"ISO time. Default: now.","type":"string"}},{"name":"interval","in":"query","required":false,"schema":{"description":"Default: hour up to 2 days, day up to 90 days, month beyond.","anyOf":[{"const":"hour","type":"string"},{"const":"day","type":"string"},{"const":"month","type":"string"}]}},{"name":"timeZone","in":"query","required":false,"schema":{"maxLength":64,"description":"IANA time zone the buckets are aligned to, e.g. Asia/Kuala_Lumpur. Default UTC.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/visits":{"get":{"operationId":"visits.list","summary":"The stored visit rows, newest first. A visitor's address is never stored; each row has a country, a device and a hash that changes daily.","x-risk":"read","x-permission":"analytics:read","parameters":[{"name":"linkId","in":"query","required":false,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"description":"Default: every kind.","anyOf":[{"const":"click","type":"string"},{"const":"bot","type":"string"},{"const":"prefetch","type":"string"},{"const":"root","type":"string"},{"const":"miss","type":"string"},{"const":"gone","type":"string"}]}},{"name":"from","in":"query","required":false,"schema":{"description":"ISO time. Default: 30 days before `to`.","type":"string"}},{"name":"to","in":"query","required":false,"schema":{"description":"ISO time. Default: now.","type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":1000,"default":100,"type":"integer"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/analytics/export":{"get":{"operationId":"visits.export","summary":"Every stored visit row in a range as a CSV file. Over REST the file is streamed.","x-risk":"read","x-permission":"analytics:read","parameters":[{"name":"linkId","in":"query","required":false,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"description":"Default: every kind.","anyOf":[{"const":"click","type":"string"},{"const":"bot","type":"string"},{"const":"prefetch","type":"string"},{"const":"root","type":"string"},{"const":"miss","type":"string"},{"const":"gone","type":"string"}]}},{"name":"from","in":"query","required":false,"schema":{"description":"ISO time. Default: 30 days before `to`.","type":"string"}},{"name":"to","in":"query","required":false,"schema":{"description":"ISO time. Default: now.","type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events":{"get":{"operationId":"events.list","summary":"The organization's change history: what changed, when, and which member, app, agent or system did it.","x-risk":"read","x-permission":"events:read","parameters":[{"name":"streamType","in":"query","required":false,"schema":{"description":"organization, principal, credential, domain, link, approval or webhook.","type":"string"}},{"name":"streamId","in":"query","required":false,"schema":{"type":"string"}},{"name":"after","in":"query","required":false,"schema":{"description":"Cursor from a previous page.","type":"integer"}},{"name":"order","in":"query","required":false,"schema":{"default":"newest","anyOf":[{"const":"oldest","type":"string"},{"const":"newest","type":"string"}]}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":200,"default":50,"type":"integer"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"get":{"operationId":"webhooks.list","summary":"List the organization's webhooks with how far each has got through the event log.","x-risk":"read","x-permission":"webhooks:manage","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"webhooks.create","summary":"Send the organization's events to an https endpoint as they happen, in order, signed. The signing secret is returned once. Events never contain visitor data.","x-risk":"write","x-permission":"webhooks:manage","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"maxLength":2048,"description":"The https endpoint that receives a POST per event.","type":"string"},"eventTypes":{"maxItems":100,"description":"Event types to deliver, e.g. link.created. Empty or absent: every type.","type":"array","items":{"type":"string"}}},"required":["url"]}}}},"responses":{"201":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhook}":{"patch":{"operationId":"webhooks.update","summary":"Change a webhook's endpoint or event types, or switch it off and on. Switching on resumes where it stopped.","x-risk":"write","x-permission":"webhooks:manage","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"maxLength":2048,"description":"The https endpoint.","type":"string"},"eventTypes":{"maxItems":100,"type":"array","items":{"type":"string"}},"status":{"anyOf":[{"const":"active","type":"string"},{"const":"disabled","type":"string"}]}},"required":[]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"webhooks.remove","summary":"Remove a webhook. Nothing more is sent to it.","x-risk":"write","x-permission":"webhooks:manage","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhook}/rotate-secret":{"post":{"operationId":"webhooks.rotateSecret","summary":"Replace a webhook's signing secret. The new secret is returned once.","x-risk":"write","x-permission":"webhooks:manage","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhook}/deliveries":{"get":{"operationId":"webhooks.deliveries","summary":"Every delivery attempt for a webhook, newest first, with the endpoint's answer.","x-risk":"read","x-permission":"webhooks:manage","parameters":[{"name":"webhook","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"minimum":1,"maximum":200,"default":50,"type":"integer"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/approvals":{"get":{"operationId":"approvals.list","summary":"List changes waiting for, or already given, a human decision.","x-risk":"read","x-permission":"approvals:decide","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/approvals/{approval}":{"get":{"operationId":"approvals.get","summary":"Get one approval, including the result once it has been approved and carried out.","x-risk":"read","parameters":[{"name":"approval","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organization":{"get":{"operationId":"organization.get","summary":"The current organization and its entitlements.","x-risk":"read","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"organization.update","summary":"Rename the organization. Status and entitlements are for platform admins.","x-risk":"write","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"maxLength":120,"type":"string"},"status":{"anyOf":[{"const":"active","type":"string"},{"const":"suspended","type":"string"}]},"entitlements":{"type":"object","patternProperties":{"^(.*)$":{}}}},"required":[]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/members":{"get":{"operationId":"members.list","summary":"List the organization's members and roles, and the people invited who have not signed in yet.","x-risk":"read","x-permission":"members:manage","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"members.set","summary":"Add a person by email, or change their role. Someone with no account yet is recorded as invited and becomes a member the first time that address signs in. No email is sent.","x-risk":"write","x-permission":"members:manage","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"maxLength":320,"type":"string"},"role":{"anyOf":[{"const":"owner","type":"string"},{"const":"admin","type":"string"},{"const":"editor","type":"string"},{"const":"viewer","type":"string"}]}},"required":["email","role"]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/members/invitations/{email}":{"delete":{"operationId":"members.withdrawInvitation","summary":"Withdraw an invitation that has not been taken up.","x-risk":"write","x-permission":"members:manage","parameters":[{"name":"email","in":"path","required":true,"schema":{"maxLength":320,"type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/members/{userId}":{"delete":{"operationId":"members.remove","summary":"Remove a member from the organization.","x-risk":"write","x-permission":"members:manage","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/principals":{"get":{"operationId":"principals.list","summary":"List service principals (apps and agents) and their credentials. Secrets are never shown.","x-risk":"read","x-permission":"credentials:manage","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"principals.create","summary":"Create a service principal for an app or an agent.","x-risk":"write","x-permission":"credentials:manage","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"maxLength":100,"type":"string"},"kind":{"anyOf":[{"const":"app","type":"string"},{"const":"agent","type":"string"}]}},"required":["name"]}}}},"responses":{"201":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/principals/{principal}/status":{"post":{"operationId":"principals.setStatus","summary":"Disable or re-enable a service principal. Disabling stops all of its credentials at once.","x-risk":"write","x-permission":"credentials:manage","parameters":[{"name":"principal","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"const":"active","type":"string"},{"const":"disabled","type":"string"}]}},"required":["status"]}}}},"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/credentials":{"post":{"operationId":"credentials.issue","summary":"Issue a credential for a service principal. The secret is returned once.","x-risk":"write","x-permission":"credentials:manage","parameters":[{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"principalId":{"type":"string"},"name":{"maxLength":100,"type":"string"},"permissions":{"minItems":1,"type":"array","items":{"type":"string"}},"restrictions":{"additionalProperties":false,"type":"object","properties":{"domains":{"type":"array","items":{"type":"string"}},"keyPrefixes":{"type":"array","items":{"type":"string"}},"destinationHosts":{"type":"array","items":{"type":"string"}}}},"expiresInDays":{"minimum":1,"maximum":3650,"type":"integer"}},"required":["principalId","name","permissions"]}}}},"responses":{"201":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/credentials/{credential}":{"delete":{"operationId":"credentials.revoke","summary":"Revoke a credential immediately.","x-risk":"write","x-permission":"credentials:manage","parameters":[{"name":"credential","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Organization","in":"header","required":false,"description":"Organization id or slug. Needed for people in more than one organization; ignored for credentials.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform/organizations":{"get":{"operationId":"platform.organizations.list","summary":"List every organization. Platform admins only.","x-risk":"read","parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"platform.organizations.create","summary":"Onboard an organization. Platform admins only.","x-risk":"write","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"maxLength":120,"type":"string"},"slug":{"maxLength":48,"type":"string"},"kind":{"anyOf":[{"const":"platform","type":"string"},{"const":"app","type":"string"},{"const":"client","type":"string"}]},"entitlements":{"type":"object","patternProperties":{"^(.*)$":{}}},"ownerEmail":{"maxLength":320,"description":"The first owner. With no account yet, they become owner at their first sign-in.","type":"string"}},"required":["name","slug"]}}}},"responses":{"201":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"credential":{"type":"apiKey","in":"header","name":"X-API-Key"},"session":{"type":"apiKey","in":"cookie","name":"better-auth.session_token"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","PERMISSION_MISSING","RESTRICTION_VIOLATED","ORGANIZATION_SUSPENDED","ENTITLEMENT_MISSING","INVALID_REQUEST","INVALID_KEY","RESERVED_KEY","INVALID_DESTINATION","INVALID_HOSTNAME","ORGANIZATION_NOT_FOUND","DOMAIN_NOT_FOUND","LINK_NOT_FOUND","CREDENTIAL_NOT_FOUND","PRINCIPAL_NOT_FOUND","MEMBER_NOT_FOUND","APPROVAL_NOT_FOUND","WEBHOOK_NOT_FOUND","NOT_FOUND","KEY_TAKEN","KEY_RETIRED","HOSTNAME_TAKEN","SLUG_TAKEN","EXTERNAL_ID_TAKEN","VERSION_CONFLICT","IDEMPOTENCY_KEY_REUSED","LINK_RETIRED","LINK_INACTIVE","KEY_FOLD_COLLISION","DOMAIN_HAS_LINKS","LAST_OWNER","APPROVAL_NOT_PENDING","APPROVAL_REQUIRED","RATE_LIMITED","KEY_GENERATION_EXHAUSTED","INTERNAL"]},"message":{"type":"string"},"details":{"type":"object"},"requestId":{"type":"string"}}}}}}},"security":[{"credential":[]},{"session":[]}]}