> ## Documentation Index > Fetch the complete documentation index at: https://uselora.dev/llms.txt > Use this file to discover all available pages before exploring further. # Add an item to a folder > 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. ## OpenAPI ````yaml /openapi.json post /v1/folders/{id}/items openapi: 3.1.0 info: title: Lora API version: 1.0.0 description: Internal API for managing company short links servers: - url: https://api.uselora.com description: Production security: - bearerAuth: [] paths: /v1/folders/{id}/items: post: 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. operationId: addFolderItem 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: >- Sentry trace ID 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: >- Sentry trace ID 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 '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: >- Sentry trace ID 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: >- Sentry trace ID 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: >- Sentry trace ID 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: >- Sentry trace ID 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. Idempotent operations (GET, DELETE) and writes that carry an `Idempotency-Key` header are safe to retry with exponential backoff. Other writes may have partially applied; surface the error to the caller instead of retrying blindly. 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: >- Sentry trace ID when available for this request. 32-character lowercase hex string. type: string pattern: ^[0-9a-f]{32}$ required: - error - code - requestId additionalProperties: false components: securitySchemes: bearerAuth: type: http scheme: bearer ````