{"openapi":"3.1.0","info":{"title":"Lora API","version":"1.0.0","description":"Lora REST API for managing workspace shortcuts, folders, tags, and QR codes.\n\n## Versioning\nAll stable endpoints are prefixed with `/v1/`. Breaking changes ship under a new path prefix (for example `/v2/`).\nNon-breaking additions (new optional fields, new endpoints) may land in the current version.\nDeprecated endpoints are announced in the [developer docs](https://uselora.dev/essentials/versioning) before removal.\n\n## Authentication\nSend `Authorization: Bearer <api_key>` on every request except `GET /v1/qr`, which also accepts anonymous callers. API keys are workspace-scoped and carry OAuth-style scopes (for example `shortcuts.write`).\n\n## Errors\n4xx and 5xx responses use a typed JSON envelope: `{ error, code?, requestId, traceId?, fieldErrors?, required_scope?, current_plan?, required_capability? }`.\nSee components `ErrorResponse`, `ErrorWithFieldErrors`, `PaymentRequiredError`, `ForbiddenError`, and `InternalError`.\n\n## Rate limits\nSuccessful responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (IETF RateLimit fields).\n429 responses include `Retry-After` (seconds). Authenticated callers are bucketed per API key; anonymous QR endpoints are bucketed per IP.\n\n## Discovery\n- OpenAPI spec: `GET https://api.uselora.com/openapi.json` (also `GET https://api.uselora.com/`)\n- RFC 9727 catalog: `GET https://www.uselora.com/.well-known/api-catalog`\n- MCP manifest: `GET https://www.uselora.com/.well-known/mcp` (server card at `/.well-known/mcp/server-card.json`)\n- MCP Streamable HTTP endpoint: `POST https://api.uselora.com/mcp`"},"servers":[{"url":"https://api.uselora.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"schemas":{"Shortcut":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The shortcut's unique ID."},"slug":{"type":"string","description":"The shortcut slug."},"url":{"type":"string","description":"Workspace-scoped shortcut URL. Open it to record a click and redirect to the destination.","examples":["https://app.uselora.com/acme/short/handbook"]},"destination":{"type":"string","description":"The shortcut's destination URL."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"iconSettings":{"description":"Structured icon recipe (glyph + background). `null` when the default monogram-on-neutral design is used.","type":["object","null"],"properties":{"background":{"type":"object","properties":{"color":{"type":["string","null"],"pattern":"^#[0-9A-F]{6}$"},"type":{"type":"string","enum":["color","neutral"]}},"required":["color","type"],"additionalProperties":false},"glyph":{"type":"object","properties":{"ref":{"type":["string","null"]},"source":{"type":"string","enum":["favicon","monogram","upload"]},"variant":{"type":"string","enum":["color","mono"]}},"required":["ref","source","variant"],"additionalProperties":false}},"required":["background","glyph"],"additionalProperties":false},"image":{"type":["string","null"]},"video":{"type":["string","null"]},"visibility":{"type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"archived":{"type":"boolean","description":"Whether the shortcut is archived. Defaults to false if not provided."},"masked":{"type":"boolean"},"passwordProtected":{"type":"boolean","description":"Whether this shortcut requires a password before redirecting. The password hash is never returned."},"expiresAt":{"type":["string","null"],"description":"The date and time when the shortcut expires."},"dynamicRouting":{"anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}],"description":"Ordered routing rules, evaluated top to bottom — the first rule whose conditions all match wins. Conditions within a rule are ANDed; values within a condition are ORed. Visitors matching no rule get the shortcut's default `destination`."},"placeholders":{"type":"array","items":{"$ref":"#/components/schemas/PlaceholderDescriptor"},"description":"Dynamic placeholders parsed from the destination URL, in template order (e.g. `{query}`). Empty for static destinations."},"folderId":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The 8-character ID of the folder this shortcut belongs to.","examples":["a1b2c3d4"]},"tagIds":{"default":[],"description":"The unique IDs of the tags assigned to the shortcut.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"default":[],"description":"Additional handles that resolve to this shortcut in the same namespace as the canonical slug.","examples":[["urlaub","ferien"]],"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"externalId":{"type":["string","null"],"description":"The shortcut ID in your system. If set, it can identify the shortcut in future API requests. The `ext_` prefix is recommended on query parameters for visual disambiguation, but the server accepts prefixed and bare values. This key is unique across your workspace."},"tenantId":{"type":["string","null"],"description":"The ID of the tenant that created the shortcut in your system. If set, it can be used to fetch all shortcuts for a tenant."},"comments":{"type":["string","null"],"description":"Comments about the shortcut."},"workspaceId":{"type":"string","description":"ID of the workspace the shortcut belongs to."},"userId":{"type":"string","description":"ID of the user who created the shortcut."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."},"metadataSync":{"type":"object","properties":{"description":{"type":"string","enum":["auto","manual"]},"title":{"type":"string","enum":["auto","manual"]}},"required":["description","title"],"additionalProperties":false,"description":"Whether `title` and `description` are still kept in sync with the destination automatically, or have been overridden by hand. The screenshot's own sync state is `previewSettings.source`."},"previewSettings":{"description":"Stored destination screenshot for the hover preview. `null` when none has been resolved yet; `source: \"none\"` when the owner declined one. Use the resolved `previewUrl` / `previewDarkUrl` to render it — `assetId` and `blobHost` describe where it is stored and are not accepted on a write.","type":["object","null"],"properties":{"assetId":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"blobHost":{"type":["string","null"],"maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+(?::\\d{1,5})?$"},"capturedAt":{"type":["string","null"],"format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"capturedFor":{"type":["string","null"],"maxLength":32000},"hasDark":{"type":"boolean"},"height":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560},"source":{"type":"string","enum":["screenshot","opengraph","upload","none"]},"width":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560}},"required":["assetId","blobHost","capturedAt","capturedFor","hasDark","height","source","width"],"additionalProperties":false},"qrSettings":{"description":"Saved QR code design for this shortcut. `null` when the default design is used. Customization requires a paid plan.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"previewUrl":{"description":"Resolved URL of the light screenshot, or `null` when there is none.","type":["string","null"]},"previewDarkUrl":{"description":"Resolved URL of the dark screenshot, or `null` when the preview has no dark variant.","type":["string","null"]},"additionalFolderIds":{"default":[],"description":"Short IDs of ADDITIONAL folders this shortcut appears in, excluding its primary folder (`folderId`). Empty array when it only lives in its primary folder. Settable at create; curate afterwards via the folder items endpoints. Folders you cannot see are omitted.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}}},"required":["archived","comments","createdAt","description","destination","dynamicRouting","expiresAt","externalId","folderId","icon","id","image","masked","metadataSync","slug","tenantId","title","updatedAt","userId","video","visibility","workspaceId","passwordProtected","previewUrl","previewDarkUrl","url","placeholders","tagIds","additionalFolderIds","aliases"],"additionalProperties":false,"title":"Shortcut","description":"A shortcut."},"CreateShortcutRequest":{"type":"object","properties":{"slug":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$","description":"The shortcut slug.","examples":["handbook"]},"destination":{"type":"string","minLength":1,"maxLength":32000,"description":"The shortcut's destination URL.","examples":["https://google.com","mailto:hello@example.com","tel:+1234567890","notion://workspace/page"]},"title":{"description":"Optional title for the shortcut","type":["string","null"]},"description":{"description":"Optional description for the shortcut","type":["string","null"]},"image":{"description":"Optional image URL","type":["string","null"]},"video":{"description":"Optional video URL","type":["string","null"]},"visibility":{"default":"WORKSPACE","description":"Visibility level of the shortcut","type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"masked":{"description":"Whether to mask the destination URL","default":false,"type":"boolean"},"password":{"description":"The password required to access the destination URL of the shortcut.","format":"password","writeOnly":true,"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"string","const":""},{"type":"null"}]},"expiresAt":{"description":"The date and time when the shortcut expires.","format":"date-time","type":["string","null"]},"dynamicRouting":{"anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}]},"folderId":{"description":"The 8-character ID of an existing folder to assign the shortcut to. Defaults to the workspace's default folder when omitted.","examples":["a1b2c3d4"],"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"},"tagIds":{"description":"The unique IDs of the tags assigned to the shortcut.","examples":[["a1b2c3d4"]],"maxItems":50,"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"description":"Optional alternate handles that resolve to this shortcut. Must be unique within the shortcut's namespace.","examples":[["urlaub"]],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"externalId":{"type":["string","null"]},"tenantId":{"type":["string","null"]},"comments":{"type":["string","null"]},"qrSettings":{"description":"Saved QR code design. Pass `null` to use the default design. Customization requires a paid plan.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"additionalFolderIds":{"description":"Short IDs of additional folders this shortcut should appear in, excluding its primary folder (`folderId`).","examples":[["a1b2c3d4"]],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}}},"required":["destination","slug"],"additionalProperties":false,"title":"CreateShortcutRequest","description":"Payload to create a new shortcut"},"Tag":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The tag's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"color":{"type":"string","enum":["DEFAULT","GRAY","BROWN","ORANGE","YELLOW","GREEN","BLUE","PURPLE","PINK","RED"]},"workspaceId":{"type":"string","description":"ID of the workspace the tag belongs to."},"creatorId":{"type":"string","description":"ID of the user who created the tag."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."}},"required":["color","createdAt","creatorId","name","slug","updatedAt","workspaceId","id"],"additionalProperties":false,"title":"Tag","description":"A tag."},"CreateTagRequest":{"type":"object","properties":{"color":{"description":"Tag color","default":"DEFAULT","examples":["BLUE"],"type":"string","enum":["DEFAULT","GRAY","BROWN","ORANGE","YELLOW","GREEN","BLUE","PURPLE","PINK","RED"]},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The tag name (3..50 chars). The slug is derived from this server-side and updates whenever `name` changes.","examples":["Marketing"]}},"required":["name"],"additionalProperties":false,"title":"CreateTagRequest","description":"Payload to create a new tag"},"Folder":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The folder's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"isSystem":{"type":"boolean","description":"True for built-in folders such as the workspace default. Folders you create are always false."},"workspaceId":{"type":"string","description":"ID of the workspace the folder belongs to."},"creatorId":{"type":"string","description":"ID of the user who created the folder."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."}},"required":["createdAt","creatorId","description","isSystem","name","slug","updatedAt","workspaceId","id"],"additionalProperties":false,"title":"Folder","description":"A folder."},"CreateFolderRequest":{"type":"object","properties":{"description":{"description":"Optional description for the folder","type":["string","null"]},"name":{"type":"string","minLength":3,"maxLength":190,"description":"The folder name (3..190 chars). The slug is derived from this server-side.","examples":["Marketing"]}},"required":["name"],"additionalProperties":false,"title":"CreateFolderRequest","description":"Payload to create a new folder"},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false},"ErrorWithFieldErrors":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false},"ForbiddenError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false},"PaymentRequiredError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false},"InternalError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false},"DynamicRouting":{"maxItems":10,"type":"array","items":{"$ref":"#/components/schemas/DynamicRoutingRule"},"title":"DynamicRouting","description":"Ordered routing rules, evaluated top to bottom — the first rule whose conditions all match wins. Conditions within a rule are ANDed; values within a condition are ORed. Visitors matching no rule get the shortcut's default `destination`. At most 10 rules. Pass `[]` or `null` to remove all rules."},"DynamicRoutingRule":{"type":"object","properties":{"conditions":{"minItems":1,"maxItems":2,"type":"array","items":{"$ref":"#/components/schemas/DynamicRoutingCondition"},"description":"Conditions to satisfy, ANDed together. At most 2 — one per attribute."},"destination":{"type":"string","minLength":1,"maxLength":32000,"description":"Where to send visitors matching this rule. Same scheme rules as the shortcut's default `destination`, and dynamic placeholders work here too.","examples":["https://apps.apple.com/de/app/id123456789"]}},"required":["conditions","destination"],"additionalProperties":false,"title":"DynamicRoutingRule","description":"A set of ANDed conditions and the destination they select."},"DynamicRoutingCondition":{"oneOf":[{"type":"object","properties":{"attribute":{"type":"string","const":"country"},"operator":{"type":"string","enum":["is","is_not"],"description":"`is` matches when the visitor attribute is one of `values`; `is_not` matches when it is not. A visitor attribute we cannot determine (no geo signal, or a non-phone / unclassifiable user agent) never satisfies `is` and always satisfies `is_not`."},"values":{"minItems":1,"maxItems":250,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"ISO-3166-1 alpha-2 country codes. Matched case-insensitively and stored uppercase.","examples":[["DE","AT","CH"]]}},"required":["attribute","operator","values"],"additionalProperties":false},{"type":"object","properties":{"attribute":{"type":"string","const":"platform"},"operator":{"type":"string","enum":["is","is_not"],"description":"`is` matches when the visitor attribute is one of `values`; `is_not` matches when it is not. A visitor attribute we cannot determine (no geo signal, or a non-phone / unclassifiable user agent) never satisfies `is` and always satisfies `is_not`."},"values":{"minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["ios","android"]},"description":"Phone platforms. Tablets, desktops and unclassifiable clients are not any of these — they fall through to `destination` unless an `is_not` condition catches them.","examples":[["ios"]]}},"required":["attribute","operator","values"],"additionalProperties":false}],"title":"DynamicRoutingCondition","description":"One test against a visitor attribute. Values inside a condition are ORed.","type":"object"},"PlaceholderDescriptor":{"type":"object","properties":{"name":{"type":"string","description":"Placeholder name (between curly braces)."},"default":{"description":"Default value substituted when no value is captured at click time.","type":["string","null"]},"label":{"default":null,"description":"Human-facing label shown on the prompt fields a visitor fills in. Null when omitted, in which case clients fall back to `name`. Never used as a query key.","type":["string","null"]}},"required":["name","default","label"],"additionalProperties":false,"title":"PlaceholderDescriptor","description":"A dynamic placeholder declared in a shortcut's destination URL."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"paths":{"/v1/shortcuts":{"post":{"operationId":"createShortcut","tags":["Shortcuts"],"summary":"Create shortcut","description":"Creates a shortcut in the workspace.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$","description":"The shortcut slug.","examples":["handbook"]},"destination":{"type":"string","minLength":1,"maxLength":32000,"description":"The shortcut's destination URL.","examples":["https://google.com","mailto:hello@example.com","tel:+1234567890","notion://workspace/page"]},"title":{"description":"Optional title for the shortcut","type":["string","null"]},"description":{"description":"Optional description for the shortcut","type":["string","null"]},"image":{"description":"Optional image URL","type":["string","null"]},"video":{"description":"Optional video URL","type":["string","null"]},"visibility":{"default":"WORKSPACE","description":"Visibility level of the shortcut","type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"masked":{"description":"Whether to mask the destination URL","default":false,"type":"boolean"},"password":{"description":"The password required to access the destination URL of the shortcut.","format":"password","writeOnly":true,"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"string","const":""},{"type":"null"}]},"expiresAt":{"description":"The date and time when the shortcut expires.","format":"date-time","type":["string","null"]},"dynamicRouting":{"anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}]},"folderId":{"description":"The 8-character ID of an existing folder to assign the shortcut to. Defaults to the workspace's default folder when omitted.","examples":["a1b2c3d4"],"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"},"tagIds":{"description":"The unique IDs of the tags assigned to the shortcut.","examples":[["a1b2c3d4"]],"maxItems":50,"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"description":"Optional alternate handles that resolve to this shortcut. Must be unique within the shortcut's namespace.","examples":[["urlaub"]],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"externalId":{"type":["string","null"]},"tenantId":{"type":["string","null"]},"comments":{"type":["string","null"]},"qrSettings":{"description":"Saved QR code design. Pass `null` to use the default design. Customization requires a paid plan.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"additionalFolderIds":{"description":"Short IDs of additional folders this shortcut should appear in, excluding its primary folder (`folderId`).","examples":[["a1b2c3d4"]],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}}},"required":["destination","slug"],"additionalProperties":false,"title":"CreateShortcutRequest","description":"Payload to create a new shortcut"}}}},"responses":{"201":{"description":"The created shortcut.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The shortcut's unique ID."},"slug":{"type":"string","description":"The shortcut slug."},"url":{"type":"string","description":"Workspace-scoped shortcut URL. Open it to record a click and redirect to the destination.","examples":["https://app.uselora.com/acme/short/handbook"]},"destination":{"type":"string","description":"The shortcut's destination URL."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"iconSettings":{"description":"Structured icon recipe (glyph + background). `null` when the default monogram-on-neutral design is used.","type":["object","null"],"properties":{"background":{"type":"object","properties":{"color":{"type":["string","null"],"pattern":"^#[0-9A-F]{6}$"},"type":{"type":"string","enum":["color","neutral"]}},"required":["color","type"],"additionalProperties":false},"glyph":{"type":"object","properties":{"ref":{"type":["string","null"]},"source":{"type":"string","enum":["favicon","monogram","upload"]},"variant":{"type":"string","enum":["color","mono"]}},"required":["ref","source","variant"],"additionalProperties":false}},"required":["background","glyph"],"additionalProperties":false},"image":{"type":["string","null"]},"video":{"type":["string","null"]},"visibility":{"type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"archived":{"type":"boolean","description":"Whether the shortcut is archived. Defaults to false if not provided."},"masked":{"type":"boolean"},"passwordProtected":{"type":"boolean","description":"Whether this shortcut requires a password before redirecting. The password hash is never returned."},"expiresAt":{"type":["string","null"],"description":"The date and time when the shortcut expires."},"dynamicRouting":{"anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}],"description":"Ordered routing rules, evaluated top to bottom — the first rule whose conditions all match wins. Conditions within a rule are ANDed; values within a condition are ORed. Visitors matching no rule get the shortcut's default `destination`."},"placeholders":{"type":"array","items":{"$ref":"#/components/schemas/PlaceholderDescriptor"},"description":"Dynamic placeholders parsed from the destination URL, in template order (e.g. `{query}`). Empty for static destinations."},"folderId":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The 8-character ID of the folder this shortcut belongs to.","examples":["a1b2c3d4"]},"tagIds":{"default":[],"description":"The unique IDs of the tags assigned to the shortcut.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"default":[],"description":"Additional handles that resolve to this shortcut in the same namespace as the canonical slug.","examples":[["urlaub","ferien"]],"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"externalId":{"type":["string","null"],"description":"The shortcut ID in your system. If set, it can identify the shortcut in future API requests. The `ext_` prefix is recommended on query parameters for visual disambiguation, but the server accepts prefixed and bare values. This key is unique across your workspace."},"tenantId":{"type":["string","null"],"description":"The ID of the tenant that created the shortcut in your system. If set, it can be used to fetch all shortcuts for a tenant."},"comments":{"type":["string","null"],"description":"Comments about the shortcut."},"workspaceId":{"type":"string","description":"ID of the workspace the shortcut belongs to."},"userId":{"type":"string","description":"ID of the user who created the shortcut."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."},"metadataSync":{"type":"object","properties":{"description":{"type":"string","enum":["auto","manual"]},"title":{"type":"string","enum":["auto","manual"]}},"required":["description","title"],"additionalProperties":false,"description":"Whether `title` and `description` are still kept in sync with the destination automatically, or have been overridden by hand. The screenshot's own sync state is `previewSettings.source`."},"previewSettings":{"description":"Stored destination screenshot for the hover preview. `null` when none has been resolved yet; `source: \"none\"` when the owner declined one. Use the resolved `previewUrl` / `previewDarkUrl` to render it — `assetId` and `blobHost` describe where it is stored and are not accepted on a write.","type":["object","null"],"properties":{"assetId":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"blobHost":{"type":["string","null"],"maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+(?::\\d{1,5})?$"},"capturedAt":{"type":["string","null"],"format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"capturedFor":{"type":["string","null"],"maxLength":32000},"hasDark":{"type":"boolean"},"height":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560},"source":{"type":"string","enum":["screenshot","opengraph","upload","none"]},"width":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560}},"required":["assetId","blobHost","capturedAt","capturedFor","hasDark","height","source","width"],"additionalProperties":false},"qrSettings":{"description":"Saved QR code design for this shortcut. `null` when the default design is used. Customization requires a paid plan.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"previewUrl":{"description":"Resolved URL of the light screenshot, or `null` when there is none.","type":["string","null"]},"previewDarkUrl":{"description":"Resolved URL of the dark screenshot, or `null` when the preview has no dark variant.","type":["string","null"]},"additionalFolderIds":{"default":[],"description":"Short IDs of ADDITIONAL folders this shortcut appears in, excluding its primary folder (`folderId`). Empty array when it only lives in its primary folder. Settable at create; curate afterwards via the folder items endpoints. Folders you cannot see are omitted.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}}},"required":["archived","comments","createdAt","description","destination","dynamicRouting","expiresAt","externalId","folderId","icon","id","image","masked","metadataSync","slug","tenantId","title","updatedAt","userId","video","visibility","workspaceId","passwordProtected","previewUrl","previewDarkUrl","url","placeholders","tagIds","additionalFolderIds","aliases"],"additionalProperties":false,"title":"Shortcut","description":"A shortcut."}}}},"400":{"description":"The request body failed validation, wasn't valid JSON, or the slug is reserved.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"The specified `folderId` does not exist in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"A shortcut with this slug already exists in the workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"413":{"description":"The request body exceeded the size limit. The body is rejected before being parsed, so no partial write occurred; retrying with a smaller payload will succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"payload_too_large"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header gives the seconds to wait before retrying. See [Rate limits](/essentials/rate-limits) for the default policy and recommended back-off.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Per RFC 9110.","schema":{"type":"integer","minimum":1}},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"get":{"operationId":"listShortcuts","tags":["Shortcuts"],"summary":"List shortcuts","description":"Returns shortcuts visible to the caller, paginated by an opaque cursor. Most-used first by default; use `sort` and `dir` to re-order, and the `tags` / `creator` / `owner` / `expired` / `passwordProtected` / `masked` parameters to filter. Deleted shortcuts are always excluded; archived ones unless `archived=true`; expired ones unless `showExpired=true` (subject to role/ownership — moderators and above see every expired shortcut they can access, other members only their own).\n\nThe query parameters mirror the in-app overview's own URL contract, so a link a user shares out of the app can be pasted here unchanged. Boolean parameters accordingly accept `1` / `0` as well as `true` / `false`; any other value is a `400 validation_error`.\n\nA cursor encodes a position in one specific ordering. Changing any ordering or filter parameter invalidates it — start the new query without a cursor rather than replaying the previous page's `nextCursor`, which returns `400 invalid_cursor`.","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination token returned as `nextCursor` from the previous page. Omit on the first request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size. Out-of-range values are clamped to [1, 100]; defaults to 50."},{"name":"externalId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":259},"description":"Filter to shortcuts whose `externalId` equals this value. The `ext_` prefix is recommended for visual disambiguation from internal IDs, but the server accepts both prefixed (`ext_<value>`) and bare (`<value>`) forms. Combine with `tenantId` for multi-tenant lookups."},{"name":"tenantId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Filter to shortcuts whose `tenantId` equals this value."},{"name":"query","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Free-text search over slug and title, using the same full-text and trigram matching as the in-app search. Results are relevance-ranked, which suppresses `nextCursor` — a search returns the first page only."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["clicks","created","trending","updated","title","myLastClick"],"default":"clicks"},"description":"Ordering. `clicks` (the default) orders by the rolling 30-day workspace click count; `trending` by 7-day relative change (only shortcuts with at least 5 clicks in each of the last two 7-day windows are scored — the rest sort last); `myLastClick` by the authenticated caller's own last click. Available on every plan: click-count *values* are gated (they are returned as `0` without the analytics entitlement) but the ordering is not. Re-orders the list, never narrows it."},{"name":"dir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort direction for the active `sort`. Shortcuts with no value for that ordering always sort last, in both directions."},{"name":"archived","in":"query","required":false,"schema":{"type":"string","enum":["true","false","1","0"],"default":"false"},"description":"Include archived shortcuts. Soft-deleted shortcuts are never returned regardless of this value."},{"name":"showExpired","in":"query","required":false,"schema":{"type":"string","enum":["true","false","1","0"],"default":"false"},"description":"Include expired shortcuts in the listing. Defaults to false. When true, workspace moderators and above see every expired shortcut they can access; other members only see expired shortcuts they own."},{"name":"tags","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated tag IDs (up to 20). Tag IDs outside this workspace match nothing. Combine with `tagsOp`."},{"name":"tagsOp","in":"query","required":false,"schema":{"type":"string","enum":["in","nin"],"default":"in"},"description":"How to apply `tags`. `in` returns shortcuts carrying at least one of them; `nin` returns shortcuts carrying none of them."},{"name":"creator","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated user IDs (up to 20) to filter by the shortcut's original creator. This does not change when a shortcut is transferred — use `owner` for the current owner."},{"name":"creatorOp","in":"query","required":false,"schema":{"type":"string","enum":["in","nin"],"default":"in"},"description":"How to apply `creator`. `in` returns shortcuts created by one of them; `nin` returns shortcuts created by none of them, including shortcuts with no recorded creator."},{"name":"owner","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated user IDs (up to 20) to filter by the shortcut's current owner."},{"name":"ownerOp","in":"query","required":false,"schema":{"type":"string","enum":["in","nin"],"default":"in"},"description":"How to apply `owner`. `in` returns shortcuts owned by one of them; `nin` returns shortcuts owned by none of them, including unowned shortcuts."},{"name":"expired","in":"query","required":false,"schema":{"type":"string","enum":["true","false","1","0"]},"description":"Filter by expiry state. `true` returns only shortcuts whose `expiresAt` has already passed (subject to the same role/ownership gate as `showExpired`); `false` returns the rest — both the ones expiring in the future and the ones with no expiry at all. Omitted means no expired/not-expired filter is applied; currently expired rows are still hidden unless `showExpired` is on. Evaluated against the server clock, so this means *currently* expired rather than *has an expiry set*, matching the redirect's `410 Gone` behaviour."},{"name":"passwordProtected","in":"query","required":false,"schema":{"type":"string","enum":["true","false","1","0"]},"description":"Filter by whether a password is set on the shortcut — the same derived flag returned as `passwordProtected` on each item. Never accepts or compares a password value. Omit to ignore."},{"name":"masked","in":"query","required":false,"schema":{"type":"string","enum":["true","false","1","0"]},"description":"Filter by destination masking. `true` returns only shortcuts that render a Lora landing page instead of redirecting straight through. Omit to ignore."}],"responses":{"200":{"description":"Paginated list of shortcuts.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"slug":{"type":"string"},"url":{"type":"string","description":"Workspace-scoped shortcut URL. Open it to record a click and redirect to the destination.","examples":["https://app.uselora.com/acme/short/handbook"]},"destination":{"type":"string"},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"iconSettings":{"description":"Structured icon recipe (glyph + background). `null` when the default monogram-on-neutral design is used.","type":["object","null"],"properties":{"background":{"type":"object","properties":{"color":{"type":["string","null"],"pattern":"^#[0-9A-F]{6}$"},"type":{"type":"string","enum":["color","neutral"]}},"required":["color","type"],"additionalProperties":false},"glyph":{"type":"object","properties":{"ref":{"type":["string","null"]},"source":{"type":"string","enum":["favicon","monogram","upload"]},"variant":{"type":"string","enum":["color","mono"]}},"required":["ref","source","variant"],"additionalProperties":false}},"required":["background","glyph"],"additionalProperties":false},"image":{"type":["string","null"]},"video":{"type":["string","null"]},"visibility":{"type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"archived":{"type":"boolean"},"masked":{"type":"boolean"},"passwordProtected":{"type":"boolean","description":"Whether this shortcut requires a password before redirecting. The password hash is never returned."},"expiresAt":{"type":["string","null"]},"placeholders":{"type":"array","items":{"$ref":"#/components/schemas/PlaceholderDescriptor"},"description":"Dynamic placeholders parsed from the destination URL, in template order (e.g. `{query}`). Empty for static destinations."},"folderId":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The 8-character ID of the folder this shortcut belongs to.","examples":["a1b2c3d4"]},"tagIds":{"default":[],"description":"Tag short IDs associated with this shortcut. Empty array when none are applied.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"default":[],"description":"Additional handles that resolve to this shortcut. The canonical slug is always `slug`; aliases are alternate names in the same namespace.","examples":[["urlaub","ferien"]],"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"externalId":{"type":["string","null"]},"tenantId":{"type":["string","null"]},"workspaceId":{"type":"string"},"userId":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"clickCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Rolling 30-day workspace click count for this shortcut. Incremented on each click; clicks that age out of the window may remain until the next nightly reconciliation. Returned as `0` without the analytics entitlement even though ordering still uses the real value. The shortcut detail endpoint returns the lifetime total instead."},"isDraft":{"type":"boolean"},"metadataSync":{"type":"object","properties":{"description":{"type":"string","enum":["auto","manual"]},"title":{"type":"string","enum":["auto","manual"]}},"required":["description","title"],"additionalProperties":false,"description":"Whether `title` and `description` are still kept in sync with the destination automatically, or have been overridden by hand. The screenshot's own sync state is `previewSettings.source`."},"previewSettings":{"description":"Stored destination screenshot for the hover preview. `null` when none has been resolved yet; `source: \"none\"` when the owner declined one. Use the resolved `previewUrl` / `previewDarkUrl` to render it — `assetId` and `blobHost` describe where it is stored and are not accepted on a write.","type":["object","null"],"properties":{"assetId":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"blobHost":{"type":["string","null"],"maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+(?::\\d{1,5})?$"},"capturedAt":{"type":["string","null"],"format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"capturedFor":{"type":["string","null"],"maxLength":32000},"hasDark":{"type":"boolean"},"height":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560},"source":{"type":"string","enum":["screenshot","opengraph","upload","none"]},"width":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560}},"required":["assetId","blobHost","capturedAt","capturedFor","hasDark","height","source","width"],"additionalProperties":false},"proxy":{"type":"boolean"},"qrSettings":{"description":"Saved QR code design for this shortcut. `null` when the default design is used. Customization requires a paid plan.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"previewUrl":{"description":"Resolved URL of the light screenshot, or `null` when there is none.","type":["string","null"]},"previewDarkUrl":{"description":"Resolved URL of the dark screenshot, or `null` when the preview has no dark variant.","type":["string","null"]},"additionalFolderIds":{"default":[],"description":"Short IDs of ADDITIONAL folders this shortcut appears in, excluding its primary folder (`folderId`). Empty array when it only lives in its primary folder. Settable at create; curate afterwards via the folder items endpoints. Folders you cannot see are omitted.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"owner":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"image":{"type":["string","null"]}},"required":["id","name","image"],"additionalProperties":false},"creator":{"description":"The user who originally created this shortcut (`created_by`). Unchanged by ownership transfer — use `owner` for the current owner.","type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"image":{"type":["string","null"]}},"required":["id","name","image"],"additionalProperties":false},"isFavorited":{"type":"boolean"}},"required":["archived","clickCount","createdAt","description","destination","expiresAt","externalId","folderId","icon","id","image","isDraft","masked","metadataSync","proxy","slug","tenantId","title","updatedAt","userId","video","visibility","workspaceId","passwordProtected","previewUrl","previewDarkUrl","url","placeholders","tagIds","additionalFolderIds","aliases","owner","creator","isFavorited"],"additionalProperties":false,"title":"ShortcutListItem","description":"A shortcut as it appears in the workspace overview listing"}},"nextCursor":{"description":"Cursor for the next page, or null if this is the last page.","type":["string","null"],"pattern":"^[A-Za-z0-9_-]{38,4096}$"}},"required":["items","nextCursor"],"additionalProperties":false,"title":"ListShortcutsResponse","description":"Paginated list of shortcuts visible to the caller"}}}},"400":{"description":"Query parameters failed validation, or the cursor was malformed (`invalid_cursor`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer","minimum":1}},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}}},"/v1/shortcuts/{handle}":{"patch":{"operationId":"updateShortcut","tags":["Shortcuts"],"summary":"Update shortcut","description":"All fields are optional. Omitted fields stay as-is. Renaming the slug runs the same reserved-word and uniqueness checks as create. `archived` is not editable here and will get its own endpoint.","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"The shortcut's slug or `id` (UUID)."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"slug":{"description":"New unique short path. Omit to keep the existing slug.","examples":["handbook"],"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"},"destination":{"description":"New destination URL. Same scheme rules as create (no javascript:/data:/file:).","examples":["https://example.com/new-target"],"type":"string","minLength":1,"maxLength":32000},"title":{"description":"New title. Pass null to clear.","type":["string","null"]},"description":{"description":"New description. Pass null to clear.","type":["string","null"]},"iconSettings":{"description":"Replace the icon recipe. Pass `null` to reset to the default. Omit to leave it untouched. The payload replaces the whole recipe — partial merges are not supported.","type":["object","null"],"properties":{"background":{"type":"object","properties":{"color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}$"},"type":{"type":"string","enum":["color","neutral"]}},"additionalProperties":false},"glyph":{"type":"object","properties":{"ref":{"type":["string","null"],"maxLength":64},"source":{"type":"string","enum":["favicon","monogram","upload"]},"variant":{"type":"string","enum":["color","mono"]}},"additionalProperties":false}},"additionalProperties":false},"visibility":{"description":"New visibility level. One of `PRIVATE`, `WORKSPACE`, or `UNLISTED`.","type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"masked":{"type":"boolean"},"password":{"description":"The password required to access the destination URL of the shortcut.","format":"password","writeOnly":true,"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"string","const":""},{"type":"null"}]},"expiresAt":{"description":"The date and time when the shortcut expires.","format":"date-time","type":["string","null"],"pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"dynamicRouting":{"description":"Replace the routing rules. Pass `[]` or `null` to remove all rules. Omit to leave them untouched.","anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}]},"folderId":{"description":"Move the shortcut to a different folder, by its 8-character ID. The caller must have access to the target folder.","type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"},"tagIds":{"description":"Replace the tag set. Pass the full set you want — existing tags not in this list are removed. Omit to leave tags untouched. Pass `[]` to clear all tags.","examples":[["a1b2c3d4"]],"maxItems":50,"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"description":"Replace the alias set. Pass the full set you want — existing aliases not in this list are removed. Omit to leave aliases untouched. Pass `[]` to clear all aliases.","examples":[["urlaub"]],"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"comments":{"description":"Comments about the shortcut.","type":["string","null"]},"proxy":{"type":"boolean"},"qrSettings":{"description":"Saved QR code design. Pass `null` to reset to the default design.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"previewSettings":{"description":"Replace the stored screenshot. Pass an `assetId` already uploaded to this workspace, `{ \"source\": \"none\" }` to decline a preview, or `null` to make it eligible for automatic capture again. Omit to leave it untouched. The payload replaces the whole record — partial merges are not supported.","type":["object","null"],"properties":{"assetId":{"type":["string","null"],"maxLength":64},"capturedAt":{"type":["string","null"],"format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"capturedFor":{"type":["string","null"],"maxLength":32000},"hasDark":{"type":["boolean","null"]},"height":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560},"source":{"type":"string","enum":["screenshot","opengraph","upload","none"]},"width":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560}},"additionalProperties":false}},"additionalProperties":false,"title":"UpdateShortcutRequest","description":"Partial shortcut update — all fields optional (PATCH semantics)."}}}},"responses":{"200":{"description":"The updated shortcut.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The shortcut's unique ID."},"slug":{"type":"string","description":"The shortcut slug."},"url":{"type":"string","description":"Workspace-scoped shortcut URL. Open it to record a click and redirect to the destination.","examples":["https://app.uselora.com/acme/short/handbook"]},"destination":{"type":"string","description":"The shortcut's destination URL."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"iconSettings":{"description":"Structured icon recipe (glyph + background). `null` when the default monogram-on-neutral design is used.","type":["object","null"],"properties":{"background":{"type":"object","properties":{"color":{"type":["string","null"],"pattern":"^#[0-9A-F]{6}$"},"type":{"type":"string","enum":["color","neutral"]}},"required":["color","type"],"additionalProperties":false},"glyph":{"type":"object","properties":{"ref":{"type":["string","null"]},"source":{"type":"string","enum":["favicon","monogram","upload"]},"variant":{"type":"string","enum":["color","mono"]}},"required":["ref","source","variant"],"additionalProperties":false}},"required":["background","glyph"],"additionalProperties":false},"image":{"type":["string","null"]},"video":{"type":["string","null"]},"visibility":{"type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"archived":{"type":"boolean","description":"Whether the shortcut is archived. Defaults to false if not provided."},"masked":{"type":"boolean"},"passwordProtected":{"type":"boolean","description":"Whether this shortcut requires a password before redirecting. The password hash is never returned."},"expiresAt":{"type":["string","null"],"description":"The date and time when the shortcut expires."},"dynamicRouting":{"anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}],"description":"Ordered routing rules, evaluated top to bottom — the first rule whose conditions all match wins. Conditions within a rule are ANDed; values within a condition are ORed. Visitors matching no rule get the shortcut's default `destination`."},"placeholders":{"type":"array","items":{"$ref":"#/components/schemas/PlaceholderDescriptor"},"description":"Dynamic placeholders parsed from the destination URL, in template order (e.g. `{query}`). Empty for static destinations."},"folderId":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The 8-character ID of the folder this shortcut belongs to.","examples":["a1b2c3d4"]},"tagIds":{"default":[],"description":"The unique IDs of the tags assigned to the shortcut.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"default":[],"description":"Additional handles that resolve to this shortcut in the same namespace as the canonical slug.","examples":[["urlaub","ferien"]],"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"externalId":{"type":["string","null"],"description":"The shortcut ID in your system. If set, it can identify the shortcut in future API requests. The `ext_` prefix is recommended on query parameters for visual disambiguation, but the server accepts prefixed and bare values. This key is unique across your workspace."},"tenantId":{"type":["string","null"],"description":"The ID of the tenant that created the shortcut in your system. If set, it can be used to fetch all shortcuts for a tenant."},"comments":{"type":["string","null"],"description":"Comments about the shortcut."},"workspaceId":{"type":"string","description":"ID of the workspace the shortcut belongs to."},"userId":{"type":"string","description":"ID of the user who created the shortcut."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."},"metadataSync":{"type":"object","properties":{"description":{"type":"string","enum":["auto","manual"]},"title":{"type":"string","enum":["auto","manual"]}},"required":["description","title"],"additionalProperties":false,"description":"Whether `title` and `description` are still kept in sync with the destination automatically, or have been overridden by hand. The screenshot's own sync state is `previewSettings.source`."},"previewSettings":{"description":"Stored destination screenshot for the hover preview. `null` when none has been resolved yet; `source: \"none\"` when the owner declined one. Use the resolved `previewUrl` / `previewDarkUrl` to render it — `assetId` and `blobHost` describe where it is stored and are not accepted on a write.","type":["object","null"],"properties":{"assetId":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"blobHost":{"type":["string","null"],"maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+(?::\\d{1,5})?$"},"capturedAt":{"type":["string","null"],"format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"capturedFor":{"type":["string","null"],"maxLength":32000},"hasDark":{"type":"boolean"},"height":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560},"source":{"type":"string","enum":["screenshot","opengraph","upload","none"]},"width":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560}},"required":["assetId","blobHost","capturedAt","capturedFor","hasDark","height","source","width"],"additionalProperties":false},"qrSettings":{"description":"Saved QR code design for this shortcut. `null` when the default design is used. Customization requires a paid plan.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"previewUrl":{"description":"Resolved URL of the light screenshot, or `null` when there is none.","type":["string","null"]},"previewDarkUrl":{"description":"Resolved URL of the dark screenshot, or `null` when the preview has no dark variant.","type":["string","null"]},"additionalFolderIds":{"default":[],"description":"Short IDs of ADDITIONAL folders this shortcut appears in, excluding its primary folder (`folderId`). Empty array when it only lives in its primary folder. Settable at create; curate afterwards via the folder items endpoints. Folders you cannot see are omitted.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}}},"required":["archived","comments","createdAt","description","destination","dynamicRouting","expiresAt","externalId","folderId","icon","id","image","masked","metadataSync","slug","tenantId","title","updatedAt","userId","video","visibility","workspaceId","passwordProtected","previewUrl","previewDarkUrl","url","placeholders","tagIds","additionalFolderIds","aliases"],"additionalProperties":false,"title":"Shortcut","description":"A shortcut."}}}},"400":{"description":"The request body failed validation, or the new slug is reserved (`reserved_slug`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"The shortcut wasn't found in this workspace (`not_found`), or the target `folderId` doesn't exist (`folder_not_found`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"Another shortcut in the workspace already uses this slug (`slug_conflict`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"413":{"description":"The request body exceeded the size limit. The body is rejected before being parsed, so no partial write occurred; retrying with a smaller payload will succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"payload_too_large"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"put":{"operationId":"upsertShortcut","tags":["Shortcuts"],"summary":"Upsert shortcut","description":"Creates a shortcut at the given slug, or updates the existing one. Returns `201` when a new shortcut is created and `200` when an existing one is updated. The handle is taken verbatim as the slug — for symmetry with `GET`/`PATCH`/`DELETE` the segment is named `{handle}`, but PUT does not resolve UUID-shaped handles to a row's ID. One guardrail: a UUID-shaped handle that collides with an existing shortcut's `id` returns `400 validation_error` (use `PATCH /v1/shortcuts/{handle}` to update by ID); UUID-shaped slugs that don't collide are accepted as slugs.","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"The shortcut's slug."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"destination":{"type":"string","minLength":1,"maxLength":32000,"description":"The shortcut's destination URL.","examples":["https://google.com","mailto:hello@example.com","tel:+1234567890","notion://workspace/page"]},"title":{"description":"Optional title for the shortcut","type":["string","null"]},"description":{"description":"Optional description for the shortcut","type":["string","null"]},"visibility":{"description":"Visibility level. Omit to keep the current value when updating an existing shortcut, or to default to `WORKSPACE` when creating a new one.","type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"masked":{"description":"Whether to mask the destination URL","default":false,"type":"boolean"},"password":{"description":"The password required to access the destination URL of the shortcut.","format":"password","writeOnly":true,"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"string","const":""},{"type":"null"}]},"expiresAt":{"description":"The date and time when the shortcut expires.","format":"date-time","type":["string","null"]},"dynamicRouting":{"anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}]},"folderId":{"description":"The 8-character ID of an existing folder to assign the shortcut to. Defaults to the workspace's default folder when omitted.","examples":["a1b2c3d4"],"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"required":["destination"],"additionalProperties":false,"title":"UpsertShortcutRequest","description":"The desired state of the shortcut at this slug. `tagIds`, `aliases`, and similar associations aren't accepted here — use `POST /v1/shortcuts` or `PATCH /v1/shortcuts/{handle}` for those."}}}},"responses":{"200":{"description":"The existing shortcut at this slug was updated.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The shortcut's unique ID."},"slug":{"type":"string","description":"The shortcut slug."},"url":{"type":"string","description":"Workspace-scoped shortcut URL. Open it to record a click and redirect to the destination.","examples":["https://app.uselora.com/acme/short/handbook"]},"destination":{"type":"string","description":"The shortcut's destination URL."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"iconSettings":{"description":"Structured icon recipe (glyph + background). `null` when the default monogram-on-neutral design is used.","type":["object","null"],"properties":{"background":{"type":"object","properties":{"color":{"type":["string","null"],"pattern":"^#[0-9A-F]{6}$"},"type":{"type":"string","enum":["color","neutral"]}},"required":["color","type"],"additionalProperties":false},"glyph":{"type":"object","properties":{"ref":{"type":["string","null"]},"source":{"type":"string","enum":["favicon","monogram","upload"]},"variant":{"type":"string","enum":["color","mono"]}},"required":["ref","source","variant"],"additionalProperties":false}},"required":["background","glyph"],"additionalProperties":false},"image":{"type":["string","null"]},"video":{"type":["string","null"]},"visibility":{"type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"archived":{"type":"boolean","description":"Whether the shortcut is archived. Defaults to false if not provided."},"masked":{"type":"boolean"},"passwordProtected":{"type":"boolean","description":"Whether this shortcut requires a password before redirecting. The password hash is never returned."},"expiresAt":{"type":["string","null"],"description":"The date and time when the shortcut expires."},"dynamicRouting":{"anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}],"description":"Ordered routing rules, evaluated top to bottom — the first rule whose conditions all match wins. Conditions within a rule are ANDed; values within a condition are ORed. Visitors matching no rule get the shortcut's default `destination`."},"placeholders":{"type":"array","items":{"$ref":"#/components/schemas/PlaceholderDescriptor"},"description":"Dynamic placeholders parsed from the destination URL, in template order (e.g. `{query}`). Empty for static destinations."},"folderId":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The 8-character ID of the folder this shortcut belongs to.","examples":["a1b2c3d4"]},"tagIds":{"default":[],"description":"The unique IDs of the tags assigned to the shortcut.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"default":[],"description":"Additional handles that resolve to this shortcut in the same namespace as the canonical slug.","examples":[["urlaub","ferien"]],"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"externalId":{"type":["string","null"],"description":"The shortcut ID in your system. If set, it can identify the shortcut in future API requests. The `ext_` prefix is recommended on query parameters for visual disambiguation, but the server accepts prefixed and bare values. This key is unique across your workspace."},"tenantId":{"type":["string","null"],"description":"The ID of the tenant that created the shortcut in your system. If set, it can be used to fetch all shortcuts for a tenant."},"comments":{"type":["string","null"],"description":"Comments about the shortcut."},"workspaceId":{"type":"string","description":"ID of the workspace the shortcut belongs to."},"userId":{"type":"string","description":"ID of the user who created the shortcut."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."},"metadataSync":{"type":"object","properties":{"description":{"type":"string","enum":["auto","manual"]},"title":{"type":"string","enum":["auto","manual"]}},"required":["description","title"],"additionalProperties":false,"description":"Whether `title` and `description` are still kept in sync with the destination automatically, or have been overridden by hand. The screenshot's own sync state is `previewSettings.source`."},"previewSettings":{"description":"Stored destination screenshot for the hover preview. `null` when none has been resolved yet; `source: \"none\"` when the owner declined one. Use the resolved `previewUrl` / `previewDarkUrl` to render it — `assetId` and `blobHost` describe where it is stored and are not accepted on a write.","type":["object","null"],"properties":{"assetId":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"blobHost":{"type":["string","null"],"maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+(?::\\d{1,5})?$"},"capturedAt":{"type":["string","null"],"format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"capturedFor":{"type":["string","null"],"maxLength":32000},"hasDark":{"type":"boolean"},"height":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560},"source":{"type":"string","enum":["screenshot","opengraph","upload","none"]},"width":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560}},"required":["assetId","blobHost","capturedAt","capturedFor","hasDark","height","source","width"],"additionalProperties":false},"qrSettings":{"description":"Saved QR code design for this shortcut. `null` when the default design is used. Customization requires a paid plan.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"previewUrl":{"description":"Resolved URL of the light screenshot, or `null` when there is none.","type":["string","null"]},"previewDarkUrl":{"description":"Resolved URL of the dark screenshot, or `null` when the preview has no dark variant.","type":["string","null"]},"additionalFolderIds":{"default":[],"description":"Short IDs of ADDITIONAL folders this shortcut appears in, excluding its primary folder (`folderId`). Empty array when it only lives in its primary folder. Settable at create; curate afterwards via the folder items endpoints. Folders you cannot see are omitted.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}}},"required":["archived","comments","createdAt","description","destination","dynamicRouting","expiresAt","externalId","folderId","icon","id","image","masked","metadataSync","slug","tenantId","title","updatedAt","userId","video","visibility","workspaceId","passwordProtected","previewUrl","previewDarkUrl","url","placeholders","tagIds","additionalFolderIds","aliases"],"additionalProperties":false,"title":"Shortcut","description":"A shortcut."}}}},"201":{"description":"A new shortcut was created at this slug.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The shortcut's unique ID."},"slug":{"type":"string","description":"The shortcut slug."},"url":{"type":"string","description":"Workspace-scoped shortcut URL. Open it to record a click and redirect to the destination.","examples":["https://app.uselora.com/acme/short/handbook"]},"destination":{"type":"string","description":"The shortcut's destination URL."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"iconSettings":{"description":"Structured icon recipe (glyph + background). `null` when the default monogram-on-neutral design is used.","type":["object","null"],"properties":{"background":{"type":"object","properties":{"color":{"type":["string","null"],"pattern":"^#[0-9A-F]{6}$"},"type":{"type":"string","enum":["color","neutral"]}},"required":["color","type"],"additionalProperties":false},"glyph":{"type":"object","properties":{"ref":{"type":["string","null"]},"source":{"type":"string","enum":["favicon","monogram","upload"]},"variant":{"type":"string","enum":["color","mono"]}},"required":["ref","source","variant"],"additionalProperties":false}},"required":["background","glyph"],"additionalProperties":false},"image":{"type":["string","null"]},"video":{"type":["string","null"]},"visibility":{"type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"archived":{"type":"boolean","description":"Whether the shortcut is archived. Defaults to false if not provided."},"masked":{"type":"boolean"},"passwordProtected":{"type":"boolean","description":"Whether this shortcut requires a password before redirecting. The password hash is never returned."},"expiresAt":{"type":["string","null"],"description":"The date and time when the shortcut expires."},"dynamicRouting":{"anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}],"description":"Ordered routing rules, evaluated top to bottom — the first rule whose conditions all match wins. Conditions within a rule are ANDed; values within a condition are ORed. Visitors matching no rule get the shortcut's default `destination`."},"placeholders":{"type":"array","items":{"$ref":"#/components/schemas/PlaceholderDescriptor"},"description":"Dynamic placeholders parsed from the destination URL, in template order (e.g. `{query}`). Empty for static destinations."},"folderId":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The 8-character ID of the folder this shortcut belongs to.","examples":["a1b2c3d4"]},"tagIds":{"default":[],"description":"The unique IDs of the tags assigned to the shortcut.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"default":[],"description":"Additional handles that resolve to this shortcut in the same namespace as the canonical slug.","examples":[["urlaub","ferien"]],"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"externalId":{"type":["string","null"],"description":"The shortcut ID in your system. If set, it can identify the shortcut in future API requests. The `ext_` prefix is recommended on query parameters for visual disambiguation, but the server accepts prefixed and bare values. This key is unique across your workspace."},"tenantId":{"type":["string","null"],"description":"The ID of the tenant that created the shortcut in your system. If set, it can be used to fetch all shortcuts for a tenant."},"comments":{"type":["string","null"],"description":"Comments about the shortcut."},"workspaceId":{"type":"string","description":"ID of the workspace the shortcut belongs to."},"userId":{"type":"string","description":"ID of the user who created the shortcut."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."},"metadataSync":{"type":"object","properties":{"description":{"type":"string","enum":["auto","manual"]},"title":{"type":"string","enum":["auto","manual"]}},"required":["description","title"],"additionalProperties":false,"description":"Whether `title` and `description` are still kept in sync with the destination automatically, or have been overridden by hand. The screenshot's own sync state is `previewSettings.source`."},"previewSettings":{"description":"Stored destination screenshot for the hover preview. `null` when none has been resolved yet; `source: \"none\"` when the owner declined one. Use the resolved `previewUrl` / `previewDarkUrl` to render it — `assetId` and `blobHost` describe where it is stored and are not accepted on a write.","type":["object","null"],"properties":{"assetId":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"blobHost":{"type":["string","null"],"maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+(?::\\d{1,5})?$"},"capturedAt":{"type":["string","null"],"format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"capturedFor":{"type":["string","null"],"maxLength":32000},"hasDark":{"type":"boolean"},"height":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560},"source":{"type":"string","enum":["screenshot","opengraph","upload","none"]},"width":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560}},"required":["assetId","blobHost","capturedAt","capturedFor","hasDark","height","source","width"],"additionalProperties":false},"qrSettings":{"description":"Saved QR code design for this shortcut. `null` when the default design is used. Customization requires a paid plan.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"previewUrl":{"description":"Resolved URL of the light screenshot, or `null` when there is none.","type":["string","null"]},"previewDarkUrl":{"description":"Resolved URL of the dark screenshot, or `null` when the preview has no dark variant.","type":["string","null"]},"additionalFolderIds":{"default":[],"description":"Short IDs of ADDITIONAL folders this shortcut appears in, excluding its primary folder (`folderId`). Empty array when it only lives in its primary folder. Settable at create; curate afterwards via the folder items endpoints. Folders you cannot see are omitted.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}}},"required":["archived","comments","createdAt","description","destination","dynamicRouting","expiresAt","externalId","folderId","icon","id","image","masked","metadataSync","slug","tenantId","title","updatedAt","userId","video","visibility","workspaceId","passwordProtected","previewUrl","previewDarkUrl","url","placeholders","tagIds","additionalFolderIds","aliases"],"additionalProperties":false,"title":"Shortcut","description":"A shortcut."}}}},"400":{"description":"The request body failed validation, wasn't valid JSON, the slug is reserved, `expiresAt` is in the past on a create (the update branch accepts past values), or the `{handle}` is a UUID that matches an existing shortcut's `id` (use `PATCH /v1/shortcuts/{handle}` to update by ID).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"The supplied `folderId` doesn't exist in this workspace (`folder_not_found`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"A shortcut at this slug exists but isn't visible to the caller (for example another user's private shortcut). Pick a different slug.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"413":{"description":"The request body exceeded the size limit. The body is rejected before being parsed, so no partial write occurred; retrying with a smaller payload will succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"payload_too_large"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteShortcut","tags":["Shortcuts"],"summary":"Delete shortcut","description":"Deletes a shortcut by handle. The handle is either the shortcut's `slug` or its `id` (UUID). The slug becomes immediately reusable for a new shortcut. Idempotent — re-deleting an already-deleted shortcut returns `not_found`.","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"The shortcut's slug or `id` (UUID)."}],"responses":{"204":{"description":"Shortcut deleted (no body)."},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"Shortcut not found in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"get":{"operationId":"getShortcutByHandle","tags":["Shortcuts"],"summary":"Retrieve shortcut","description":"Returns a shortcut by its handle. The handle is either the shortcut's `slug` or its `id` (UUID). Archived shortcuts are returned.","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"The shortcut's slug or `id` (UUID)."}],"responses":{"200":{"description":"The shortcut.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The shortcut's unique ID."},"slug":{"type":"string","description":"The shortcut slug."},"url":{"type":"string","description":"Workspace-scoped shortcut URL. Open it to record a click and redirect to the destination.","examples":["https://app.uselora.com/acme/short/handbook"]},"destination":{"type":"string","description":"The shortcut's destination URL."},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"icon":{"type":["string","null"]},"iconSettings":{"description":"Structured icon recipe (glyph + background). `null` when the default monogram-on-neutral design is used.","type":["object","null"],"properties":{"background":{"type":"object","properties":{"color":{"type":["string","null"],"pattern":"^#[0-9A-F]{6}$"},"type":{"type":"string","enum":["color","neutral"]}},"required":["color","type"],"additionalProperties":false},"glyph":{"type":"object","properties":{"ref":{"type":["string","null"]},"source":{"type":"string","enum":["favicon","monogram","upload"]},"variant":{"type":"string","enum":["color","mono"]}},"required":["ref","source","variant"],"additionalProperties":false}},"required":["background","glyph"],"additionalProperties":false},"image":{"type":["string","null"]},"video":{"type":["string","null"]},"visibility":{"type":"string","enum":["PRIVATE","WORKSPACE","UNLISTED"]},"archived":{"type":"boolean","description":"Whether the shortcut is archived. Defaults to false if not provided."},"masked":{"type":"boolean"},"passwordProtected":{"type":"boolean","description":"Whether this shortcut requires a password before redirecting. The password hash is never returned."},"expiresAt":{"type":["string","null"],"description":"The date and time when the shortcut expires."},"dynamicRouting":{"anyOf":[{"$ref":"#/components/schemas/DynamicRouting"},{"type":"null"}],"description":"Ordered routing rules, evaluated top to bottom — the first rule whose conditions all match wins. Conditions within a rule are ANDed; values within a condition are ORed. Visitors matching no rule get the shortcut's default `destination`."},"placeholders":{"type":"array","items":{"$ref":"#/components/schemas/PlaceholderDescriptor"},"description":"Dynamic placeholders parsed from the destination URL, in template order (e.g. `{query}`). Empty for static destinations."},"folderId":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The 8-character ID of the folder this shortcut belongs to.","examples":["a1b2c3d4"]},"tagIds":{"default":[],"description":"The unique IDs of the tags assigned to the shortcut.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"aliases":{"default":[],"description":"Additional handles that resolve to this shortcut in the same namespace as the canonical slug.","examples":[["urlaub","ferien"]],"type":"array","items":{"type":"string","minLength":1,"maxLength":50,"pattern":"^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$"}},"externalId":{"type":["string","null"],"description":"The shortcut ID in your system. If set, it can identify the shortcut in future API requests. The `ext_` prefix is recommended on query parameters for visual disambiguation, but the server accepts prefixed and bare values. This key is unique across your workspace."},"tenantId":{"type":["string","null"],"description":"The ID of the tenant that created the shortcut in your system. If set, it can be used to fetch all shortcuts for a tenant."},"comments":{"type":["string","null"],"description":"Comments about the shortcut."},"workspaceId":{"type":"string","description":"ID of the workspace the shortcut belongs to."},"userId":{"type":"string","description":"ID of the user who created the shortcut."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."},"metadataSync":{"type":"object","properties":{"description":{"type":"string","enum":["auto","manual"]},"title":{"type":"string","enum":["auto","manual"]}},"required":["description","title"],"additionalProperties":false,"description":"Whether `title` and `description` are still kept in sync with the destination automatically, or have been overridden by hand. The screenshot's own sync state is `previewSettings.source`."},"previewSettings":{"description":"Stored destination screenshot for the hover preview. `null` when none has been resolved yet; `source: \"none\"` when the owner declined one. Use the resolved `previewUrl` / `previewDarkUrl` to render it — `assetId` and `blobHost` describe where it is stored and are not accepted on a write.","type":["object","null"],"properties":{"assetId":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"},"blobHost":{"type":["string","null"],"maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+(?::\\d{1,5})?$"},"capturedAt":{"type":["string","null"],"format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"capturedFor":{"type":["string","null"],"maxLength":32000},"hasDark":{"type":"boolean"},"height":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560},"source":{"type":"string","enum":["screenshot","opengraph","upload","none"]},"width":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":2560}},"required":["assetId","blobHost","capturedAt","capturedFor","hasDark","height","source","width"],"additionalProperties":false},"qrSettings":{"description":"Saved QR code design for this shortcut. `null` when the default design is used. Customization requires a paid plan.","type":["object","null"],"properties":{"dotColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"dotStyle":{"type":"string","enum":["square","dots","rounded"]},"frame":{"type":"string","enum":["none","solid-logo","solid-scan","solid-slug","window-logo","window-scan","window-slug","card-logo","card-scan","card-slug"]},"hideLogo":{"type":"boolean"},"markerBorder":{"type":"string","enum":["square","rounded","circle"]},"markerCenter":{"type":"string","enum":["square","dot"]},"markerColor":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"}},"additionalProperties":false},"previewUrl":{"description":"Resolved URL of the light screenshot, or `null` when there is none.","type":["string","null"]},"previewDarkUrl":{"description":"Resolved URL of the dark screenshot, or `null` when the preview has no dark variant.","type":["string","null"]},"additionalFolderIds":{"default":[],"description":"Short IDs of ADDITIONAL folders this shortcut appears in, excluding its primary folder (`folderId`). Empty array when it only lives in its primary folder. Settable at create; curate afterwards via the folder items endpoints. Folders you cannot see are omitted.","examples":[["a1b2c3d4"]],"type":"array","items":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$"}}},"required":["archived","comments","createdAt","description","destination","dynamicRouting","expiresAt","externalId","folderId","icon","id","image","masked","metadataSync","slug","tenantId","title","updatedAt","userId","video","visibility","workspaceId","passwordProtected","previewUrl","previewDarkUrl","url","placeholders","tagIds","additionalFolderIds","aliases"],"additionalProperties":false,"title":"Shortcut","description":"A shortcut."}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"Shortcut not found in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}}},"/v1/tags":{"post":{"operationId":"createTag","tags":["Tags"],"summary":"Create tag","description":"Creates a new tag in the specified workspace.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"description":"Tag color","default":"DEFAULT","examples":["BLUE"],"type":"string","enum":["DEFAULT","GRAY","BROWN","ORANGE","YELLOW","GREEN","BLUE","PURPLE","PINK","RED"]},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The tag name (3..50 chars). The slug is derived from this server-side and updates whenever `name` changes.","examples":["Marketing"]}},"required":["name"],"additionalProperties":false,"title":"CreateTagRequest","description":"Payload to create a new tag"}}}},"responses":{"201":{"description":"The created tag.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The tag's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"color":{"type":"string","enum":["DEFAULT","GRAY","BROWN","ORANGE","YELLOW","GREEN","BLUE","PURPLE","PINK","RED"]},"workspaceId":{"type":"string","description":"ID of the workspace the tag belongs to."},"creatorId":{"type":"string","description":"ID of the user who created the tag."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."}},"required":["color","createdAt","creatorId","name","slug","updatedAt","workspaceId","id"],"additionalProperties":false,"title":"Tag","description":"A tag."}}}},"400":{"description":"The request body failed validation or wasn't valid JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"A tag with this name already exists in the workspace (`tag_name_exists`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"413":{"description":"The request body exceeded the size limit. The body is rejected before being parsed, so no partial write occurred; retrying with a smaller payload will succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"payload_too_large"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer","minimum":1}},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"get":{"operationId":"listTags","tags":["Tags"],"summary":"List tags","description":"Returns tags in the workspace, ordered newest-first, paginated by an opaque cursor. Deleted tags are excluded.","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination token returned as `nextCursor` from the previous page. Omit on the first request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size. Out-of-range values are clamped to [1, 100]; defaults to 50."}],"responses":{"200":{"description":"Paginated list of tags.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The tag's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"color":{"type":"string","enum":["DEFAULT","GRAY","BROWN","ORANGE","YELLOW","GREEN","BLUE","PURPLE","PINK","RED"]},"workspaceId":{"type":"string"},"creatorId":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["color","createdAt","creatorId","name","slug","updatedAt","workspaceId","id"],"additionalProperties":false,"title":"TagListItem","description":"A tag as it appears in the workspace listing"}},"nextCursor":{"description":"Opaque pagination token returned as `nextCursor` from the previous page.","type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z__[0-9abcdefghjkmnpqrstvwxyz]{8}$","examples":["2024-01-15T12:34:56.789Z__a1b2c3d4"]}},"required":["items","nextCursor"],"additionalProperties":false,"title":"ListTagsResponse","description":"Paginated list of tags visible to the caller"}}}},"400":{"description":"The cursor is malformed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}}},"/v1/tags/{id}":{"patch":{"operationId":"updateTag","tags":["Tags"],"summary":"Update tag","description":"All fields are optional. Renaming a tag updates its slug and runs the same uniqueness check as create.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","example":"a1b2c3d4"},"description":"The tag's unique ID."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"color":{"description":"Tag color","default":"DEFAULT","examples":["BLUE"],"type":"string","enum":["DEFAULT","GRAY","BROWN","ORANGE","YELLOW","GREEN","BLUE","PURPLE","PINK","RED"]},"name":{"type":"string","minLength":3,"maxLength":50,"description":"The tag name (3..50 chars). The slug is derived from this server-side and updates whenever `name` changes.","examples":["Marketing"]}},"additionalProperties":false,"title":"UpdateTagRequest","description":"Payload to update a tag"}}}},"responses":{"200":{"description":"The updated tag.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The tag's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"color":{"type":"string","enum":["DEFAULT","GRAY","BROWN","ORANGE","YELLOW","GREEN","BLUE","PURPLE","PINK","RED"]},"workspaceId":{"type":"string","description":"ID of the workspace the tag belongs to."},"creatorId":{"type":"string","description":"ID of the user who created the tag."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."}},"required":["color","createdAt","creatorId","name","slug","updatedAt","workspaceId","id"],"additionalProperties":false,"title":"Tag","description":"A tag."}}}},"400":{"description":"The request body failed validation or wasn't valid JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"Tag not found in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"Another tag in the workspace already has this name (`tag_name_exists`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"413":{"description":"The request body exceeded the size limit. The body is rejected before being parsed, so no partial write occurred; retrying with a smaller payload will succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"payload_too_large"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteTag","tags":["Tags"],"summary":"Delete tag","description":"Soft-deletes the tag. Idempotent — re-deleting an already-deleted tag returns `not_found`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","example":"a1b2c3d4"},"description":"The tag's unique ID."}],"responses":{"204":{"description":"Tag deleted (no body)."},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"Tag not found in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"get":{"operationId":"getTagById","tags":["Tags"],"summary":"Retrieve tag","description":"Returns a tag by its ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","example":"a1b2c3d4"},"description":"The tag's unique ID."}],"responses":{"200":{"description":"The tag.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The tag's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"color":{"type":"string","enum":["DEFAULT","GRAY","BROWN","ORANGE","YELLOW","GREEN","BLUE","PURPLE","PINK","RED"]},"workspaceId":{"type":"string","description":"ID of the workspace the tag belongs to."},"creatorId":{"type":"string","description":"ID of the user who created the tag."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."}},"required":["color","createdAt","creatorId","name","slug","updatedAt","workspaceId","id"],"additionalProperties":false,"title":"Tag","description":"A tag."}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"Tag not found in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}}},"/v1/folders":{"post":{"operationId":"createFolder","tags":["Folders"],"summary":"Create folder","description":"Creates a folder in the workspace. Folder names must be unique within the workspace.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"description":"Optional description for the folder","type":["string","null"]},"name":{"type":"string","minLength":3,"maxLength":190,"description":"The folder name (3..190 chars). The slug is derived from this server-side.","examples":["Marketing"]}},"required":["name"],"additionalProperties":false,"title":"CreateFolderRequest","description":"Payload to create a new folder"}}}},"responses":{"201":{"description":"The created folder.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The folder's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"isSystem":{"type":"boolean","description":"True for built-in folders such as the workspace default. Folders you create are always false."},"workspaceId":{"type":"string","description":"ID of the workspace the folder belongs to."},"creatorId":{"type":"string","description":"ID of the user who created the folder."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."}},"required":["createdAt","creatorId","description","isSystem","name","slug","updatedAt","workspaceId","id"],"additionalProperties":false,"title":"Folder","description":"A folder."}}}},"400":{"description":"The request body failed validation (for example `name` is missing or longer than 190 characters) or wasn't valid JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"A folder with this name already exists in the workspace (`folder_name_exists`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"413":{"description":"The request body exceeded the size limit. The body is rejected before being parsed, so no partial write occurred; retrying with a smaller payload will succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"payload_too_large"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer","minimum":1}},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"get":{"operationId":"listFolders","tags":["Folders"],"summary":"List folders","description":"Returns folders in the workspace, ordered newest-first, paginated by an opaque cursor. Deleted folders are excluded.","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination token returned as `nextCursor` from the previous page. Omit on the first request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Page size. Out-of-range values are clamped to [1, 100]; defaults to 50."}],"responses":{"200":{"description":"Paginated list of folders.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The folder's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"linkCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of shortcuts visible to you in this folder — those whose primary folder this is, plus those curated into it. Excludes deleted and archived shortcuts. Counted per viewer, so two members may see different values for the same folder.","examples":[12]},"isSystem":{"type":"boolean"},"workspaceId":{"type":"string"},"creatorId":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["createdAt","creatorId","isSystem","name","slug","updatedAt","workspaceId","id","linkCount"],"additionalProperties":false,"title":"FolderListItem","description":"A folder as it appears in the workspace listing"}},"nextCursor":{"description":"Cursor for the next page, or null if this is the last page.","type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z__[0-9abcdefghjkmnpqrstvwxyz]{8}$"}},"required":["items","nextCursor"],"additionalProperties":false,"title":"ListFoldersResponse","description":"Paginated list of folders visible to the caller"}}}},"400":{"description":"Query parameters failed validation, or the cursor was malformed (`invalid_cursor`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer","minimum":1}},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}}},"/v1/folders/{id}":{"patch":{"operationId":"updateFolder","tags":["Folders"],"summary":"Update folder","description":"All fields are optional. Omitted fields stay as-is. Renaming a folder updates its slug and runs the same uniqueness check as create. The workspace's default folder cannot be edited.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","example":"a1b2c3d4"},"description":"The folder's unique ID."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"description":"Optional description for the folder","type":["string","null"]},"name":{"type":"string","minLength":3,"maxLength":190,"description":"The folder name (3..190 chars). The slug is derived from this server-side.","examples":["Marketing"]}},"additionalProperties":false,"title":"UpdateFolderRequest","description":"Payload to update a folder"}}}},"responses":{"200":{"description":"The updated folder.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The folder's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"isSystem":{"type":"boolean","description":"True for built-in folders such as the workspace default. Folders you create are always false."},"workspaceId":{"type":"string","description":"ID of the workspace the folder belongs to."},"creatorId":{"type":"string","description":"ID of the user who created the folder."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."}},"required":["createdAt","creatorId","description","isSystem","name","slug","updatedAt","workspaceId","id"],"additionalProperties":false,"title":"Folder","description":"A folder."}}}},"400":{"description":"The request body failed validation or wasn't valid JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`), the caller is no longer a workspace member (`no_permission`), or the target is the workspace's default folder (`system_folder`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"Folder not found in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"Another folder in the workspace already has this name (`folder_name_exists`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"413":{"description":"The request body exceeded the size limit. The body is rejected before being parsed, so no partial write occurred; retrying with a smaller payload will succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"payload_too_large"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"delete":{"operationId":"deleteFolder","tags":["Folders"],"summary":"Delete folder","description":"Deletes a folder. Re-deleting an already-deleted folder returns `not_found`. The workspace's default folder cannot be deleted, and folders that still contain shortcuts return `folder_not_empty`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","example":"a1b2c3d4"},"description":"The folder's unique ID."}],"responses":{"204":{"description":"Folder deleted (no body)."},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`), the caller is no longer a workspace member (`no_permission`), or the target is the workspace's default folder (`system_folder`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"Folder not found in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"The folder still contains shortcuts (`folder_not_empty`). Move or delete them first.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}},"get":{"operationId":"getFolderById","tags":["Folders"],"summary":"Retrieve folder","description":"Returns a folder by its ID.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","example":"a1b2c3d4"},"description":"The folder's unique ID."}],"responses":{"200":{"description":"The folder.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","description":"The folder's unique ID.","examples":["a1b2c3d4"]},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"isSystem":{"type":"boolean","description":"True for built-in folders such as the workspace default. Folders you create are always false."},"workspaceId":{"type":"string","description":"ID of the workspace the folder belongs to."},"creatorId":{"type":"string","description":"ID of the user who created the folder."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last update."}},"required":["createdAt","creatorId","description","isSystem","name","slug","updatedAt","workspaceId","id"],"additionalProperties":false,"title":"Folder","description":"A folder."}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The caller is authenticated but not allowed to perform this action. Common codes: `insufficient_scope` (the key lacks the required scope; body sets `required_scope`) and `no_permission` (the caller is no longer a workspace member).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"Folder not found in this workspace.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}}},"/v1/folders/{id}/items":{"post":{"operationId":"addFolderItem","tags":["Folders"],"summary":"Add an item to a folder","description":"Adds an existing item to this folder as an **additional** appearance. The item's primary folder is unchanged — to move it, `PATCH /v1/shortcuts/{handle}` with a new `folderId`. Adding an item to a folder never changes who can see that item: visibility lives on the item, and a folder only filters. Idempotent — adding an item that already appears in the folder succeeds without creating a duplicate. An item may appear in at most 20 additional folders.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","example":"a1b2c3d4"},"description":"The folder's unique ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$","description":"The ID of the item to add to this folder","examples":["019e8ef6-9a84-7de9-877d-9e9ee171a8c2"]},"itemType":{"default":"shortcut","type":"string","enum":["shortcut"],"description":"The kind of item. Only `shortcut` is supported today.","examples":["shortcut"]}},"required":["itemId"],"additionalProperties":false,"title":"AddFolderItemRequest","description":"Payload to add an existing item to a folder"}}}},"responses":{"201":{"description":"Item added to the folder (or already present).","content":{"application/json":{"schema":{"type":"object","required":["added"],"properties":{"added":{"type":"boolean","enum":[true]}}}}}},"400":{"description":"The request body failed validation (for example `itemId` is missing or not a UUID) or wasn't valid JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`), or the caller may not curate this folder (`no_permission`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"The folder or the item was not found in this workspace. Items you cannot see report `not_found` rather than `no_permission`, so this endpoint cannot be used to probe for another member's private shortcuts.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"The folder is already the item's primary folder (`already_primary`), or the item has reached the additional-folder cap (`too_many_folders`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"413":{"description":"The request body exceeded the size limit. The body is rejected before being parsed, so no partial write occurred; retrying with a smaller payload will succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"payload_too_large"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}}},"/v1/folders/{id}/items/{itemType}/{itemId}":{"delete":{"operationId":"removeFolderItem","tags":["Folders"],"summary":"Remove an item from a folder","description":"Removes an item's **additional** appearance from this folder. The item itself is not deleted and keeps its primary folder. An item whose primary folder is this folder cannot be removed this way — it would be left without a canonical location; move it instead.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9abcdefghjkmnpqrstvwxyz]{8}$","example":"a1b2c3d4"},"description":"The folder's unique ID."},{"name":"itemType","in":"path","required":true,"schema":{"type":"string","enum":["shortcut"],"example":"shortcut"},"description":"The kind of item. Only `shortcut` is supported today."},{"name":"itemId","in":"path","required":true,"schema":{"type":"string","format":"uuid","example":"019e8ef6-9a84-7de9-877d-9e9ee171a8c2"},"description":"The item's ID."}],"responses":{"204":{"description":"Item removed from the folder (no body)."},"400":{"description":"The item reference in the path failed validation (unknown `itemType`, or `itemId` is not a UUID).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"fieldErrors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Missing, malformed, unknown, or workspace-unscoped Bearer token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"The workspace plan does not include API access, the requested capability, or enough resource capacity. The body uses `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace or change the request; retrying the same request will not succeed.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["plan_requires_upgrade","quota_exceeded"]},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"current_plan":{"description":"The workspace plan when the response includes it.","type":"string"},"required_capability":{"description":"The required plan capability when the response includes it.","type":"string"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"403":{"description":"The key lacks the required scope (`insufficient_scope`), or the caller may not curate this folder (`no_permission`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"},"required_scope":{"description":"Set when `code` is `insufficient_scope`. The exact scope name the route required, e.g. `shortcuts.write`.","type":"string"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"404":{"description":"The folder or item was not found, or the item does not appear in this folder.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"409":{"description":"The folder is the item's primary folder (`already_primary`). Move the item instead of removing it.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Wait `Retry-After` seconds before retrying.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the rate-limit window resets."},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}}},"500":{"description":"An unexpected failure on the server. The body is `{ error: <message>, code: \"internal_error\", requestId: <id> }`, plus `traceId` when available. Retry idempotent operations with exponential backoff. A write may already have applied; reconcile its state before retrying.","headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"internal_error"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}}}}},"/v1/qr":{"get":{"operationId":"getQRCode","tags":["QR Codes"],"summary":"Retrieve QR code","description":"Generates a PNG image of a QR code for the given URL. Accepts both anonymous and Bearer-authenticated callers; anonymous responses encode a `lora-links.com` redirect URL, authenticated responses encode the destination verbatim and may use `hideLogo` on Basic / Business / Enterprise plans.","security":[{},{"bearerAuth":[]}],"x-hidden":false,"parameters":[{"name":"url","in":"query","required":true,"description":"The URL to generate a QR code for. Anonymous calls encode this destination behind a `lora-links.com` redirect (so Lora can layer analytics and abuse-blocking on the public flow); authenticated calls (Bearer API key) encode it verbatim.","schema":{"type":"string","maxLength":32000,"examples":["https://example.com"]}},{"name":"size","in":"query","required":false,"description":"The size of the QR code in pixels (64-2048). Defaults to `600` if not provided.","schema":{"default":600,"type":"integer"}},{"name":"level","in":"query","required":false,"description":"The level of error correction to use for the QR code. Defaults to `L` if not provided.","schema":{"default":"L","type":"string","enum":["L","M","Q","H"]}},{"name":"fgColor","in":"query","required":false,"description":"The foreground color of the QR code in hex format. Defaults to `#000000` if not provided.","schema":{"default":"#000000","type":"string"}},{"name":"bgColor","in":"query","required":false,"description":"The background color of the QR code in hex format. Defaults to `#ffffff` if not provided.","schema":{"default":"#FFFFFF","type":"string"}},{"name":"hideLogo","in":"query","required":false,"description":"Whether to hide the Lora logo overlay in the QR code. Requires an authenticated request (`Authorization: Bearer …`) with an API key on a Basic, Business, or Enterprise plan. Anonymous calls receive `403 plan_requires_upgrade`; a valid Free-plan key receives `402 plan_requires_upgrade` before QR options are evaluated.","schema":{"default":false,"type":"boolean"}},{"name":"margin","in":"query","required":false,"description":"The size of the margin around the QR code in modules (0-20). Defaults to 2 if not provided.","schema":{"default":2,"type":"integer"}}],"responses":{"200":{"description":"The QR code as PNG bytes.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The request failed validation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"401":{"description":"Sent an `Authorization` header but the Bearer token was missing, malformed, unknown, expired, or disabled. A disabled key returns `code: \"apikey_disabled\"`; the other cases use the generic error envelope without a code.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"402":{"description":"A valid API key belongs to a Free workspace. Public API access requires Basic or above. The body carries `code: \"plan_requires_upgrade\"` and `current_plan: \"free\"`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"plan_requires_upgrade"},"current_plan":{"type":"string","const":"free"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","current_plan","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"403":{"description":"An anonymous caller requested `hideLogo=true`. The body carries `code: \"plan_requires_upgrade\"`, `current_plan: \"anonymous\"`, and `required_capability: \"removeWatermark\"`.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"plan_requires_upgrade","description":"Always the literal string `plan_requires_upgrade`. Clients can switch on this value to surface an upgrade CTA."},"current_plan":{"type":"string","const":"anonymous","description":"The caller is anonymous."},"required_capability":{"type":"string","const":"removeWatermark","description":"The capability required to hide the Lora logo."},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","current_plan","required_capability","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}},"429":{"description":"Rate limit exceeded. Anonymous callers share a per-IP budget (60 requests/minute, sliding window). Authenticated callers are bucketed by the workspace's per-key cap (600/minute on Basic, 1500/minute on Business and Enterprise). Requests that present an `Authorization` header are additionally subject to a per-IP cap on failed verification attempts (60/minute, sliding window): once an IP exhausts that budget, further requests with an unverified Bearer token receive this 429 before the key is checked, and valid keys never count toward it. The body uses the standard error envelope with `code: \"rate_limit_exceeded\"`. The `Retry-After` response header contains the number of seconds (≥ 1, ≤ window) the client should wait. The 429 response is never CDN-cached (`Cache-Control: no-store`) so a single blocked edge POP doesn't lock out every visitor behind it.","headers":{"Retry-After":{"description":"Seconds the client should wait before retrying. Always a positive integer, never larger than the rate-limit window.","schema":{"type":"integer","minimum":1,"maximum":60}},"Cache-Control":{"description":"Always `no-store` on the 429 response so a CDN POP can't memoize the denial and lock out every visitor behind it until the cache entry expires.","schema":{"type":"string","enum":["no-store"]}},"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"rate_limit_exceeded","description":"Always the literal string `rate_limit_exceeded`. Clients can switch on this value to surface a back-off UX."},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","code","requestId"],"additionalProperties":false}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"requestId":{"type":"string","description":"Correlation identifier for support/debugging. Equals the `X-Lora-Request-Id` response header."},"traceId":{"description":"Trace identifier when available for this request. 32-character lowercase hex string.","type":"string","pattern":"^[0-9a-f]{32}$"}},"required":["error","requestId"],"additionalProperties":false}}},"headers":{"X-Lora-Request-Id":{"description":"Request correlation identifier. Matches the `requestId` field in the JSON error body.","schema":{"type":"string"}}}}}}}}}