> ## Documentation Index > Fetch the complete documentation index at: https://uselora.dev/llms.txt > Use this file to discover all available pages before exploring further. # List shortcuts > 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). The 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`. A 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`. ## OpenAPI ````yaml /openapi.json get /v1/shortcuts 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. ## Versioning All stable endpoints are prefixed with `/v1/`. Breaking changes ship under a new path prefix (for example `/v2/`). Non-breaking additions (new optional fields, new endpoints) may land in the current version. Deprecated endpoints are announced in the [developer docs](https://uselora.dev) before removal. ## Authentication Send `Authorization: Bearer ` 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`). ## Errors 4xx and 5xx responses use a typed JSON envelope: `{ error, code?, requestId, traceId?, fieldErrors?, required_scope?, current_plan?, required_capability? }`. See components `ErrorResponse`, `ErrorWithFieldErrors`, `PaymentRequiredError`, `ForbiddenError`, and `InternalError`. ## Rate limits Successful responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (IETF RateLimit fields). 429 responses include `Retry-After` (seconds). Authenticated callers are bucketed per API key; anonymous QR endpoints are bucketed per IP. ## Discovery - OpenAPI spec: `GET https://api.uselora.com/openapi.json` (also `GET https://api.uselora.com/`) - RFC 9727 catalog: `GET https://www.uselora.com/.well-known/api-catalog` - MCP manifest: `GET https://www.uselora.com/.well-known/mcp` (server card at `/.well-known/mcp/server-card.json`) - MCP Streamable HTTP endpoint: `POST https://api.uselora.com/mcp` servers: - url: https://api.uselora.com description: Production security: - bearerAuth: [] paths: /v1/shortcuts: get: 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). The 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`. A 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`. operationId: listShortcuts 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_`) and bare (``) 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: 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: , code: "internal_error", requestId: }`, 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 components: schemas: 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 ````