Folders

Folders group your short links into a nested hierarchy so large libraries stay organized. A link carries an optional folderId; folders can be nested up to 5 levels deep. Requires links:read / links:write scopes. Available on all tiers.

Create a folder

curl -X POST https://api.short.leonai.io/api/v1/folders \
  -H "X-API-Key: $LEONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Campaigns",
    "parentId": null
  }'

Response (201 Created):

{
  "success": true,
  "data": {
    "id": "fld_...",
    "name": "Q2 Campaigns",
    "parentId": null,
    "depth": 0,
    "linkCount": 0,
    "createdAt": "2026-07-11T12:00:00.000Z"
  }
}

Pass a parentId to nest a folder inside another. REST: POST /api/v1/folders.

List, update, delete

# List your folders (tree)
curl https://api.short.leonai.io/api/v1/folders \
  -H "X-API-Key: $LEONAI_API_KEY"

# Rename or re-parent a folder
curl -X PATCH https://api.short.leonai.io/api/v1/folders/<folderId> \
  -H "X-API-Key: $LEONAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Q2 2026" }'

# Delete a folder
curl -X DELETE https://api.short.leonai.io/api/v1/folders/<folderId> \
  -H "X-API-Key: $LEONAI_API_KEY"

REST: GET /api/v1/folders, PATCH /api/v1/folders/:id, DELETE /api/v1/folders/:id.

Deleting is non-destructive

Deleting a folder keeps its links — they are detached (their folderId becomes null, moving them back to the root). Any child folders are reparented to the deleted folder's parent, so nothing is lost.

Assign links to a folder

Move a set of links into a folder in one call:

curl -X PUT https://api.short.leonai.io/api/v1/folders/<folderId>/links \
  -H "X-API-Key: $LEONAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "linkIds": ["link_1", "link_2"] }'

REST: PUT /api/v1/folders/:id/links. This replaces each listed link's folderId.

Filter links by folder

The Links list endpoint accepts a folderId query parameter. Pass a folder id to list its links, or the literal root to list links that aren't in any folder:

# Links inside a folder
curl "https://api.short.leonai.io/api/v1/links?folderId=<folderId>" \
  -H "X-API-Key: $LEONAI_API_KEY"

# Links not in any folder
curl "https://api.short.leonai.io/api/v1/links?folderId=root" \
  -H "X-API-Key: $LEONAI_API_KEY"

REST: GET /api/v1/links?folderId={id|root}.

Error codes

Status	When
400	Nesting would exceed the max depth of 5, or invalid parentId
404	Folder (or a listed link) not found / not owned by you

Related

• Links — the folderId field and ?folderId= filter
• API Reference — the full OpenAPI spec and Swagger UI