---
agentTools:
  projectIndex: https://elai.readme.io/llms.txt
---

# List media library assets

Lists the workspace's uploaded assets, newest-updated first by default. `frame`, `audio` and `logo` assets are always excluded — use `GET /uploads/frames` and `GET /uploads/music` for those.

When no `uploadFolderId`, `q` or `type` filter is given, only assets at the **root** of the media library are returned (those with no folder). Supplying any of those three filters searches across folders instead.

Every returned `url` and `thumbnail` is a time-limited signed URL — fetch the bytes promptly rather than storing the URL.

```curl Request
curl -X GET 'https://apis.elai.io/api/v1/uploads' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

# OpenAPI definition

````json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Elai Public API",
    "version": "1.0",
    "description": "Every endpoint below is served under `https://apis.elai.io/api/v1`.\n\n## Authentication\n\nSend your workspace API token as a bearer token on every request:\n\n```\nAuthorization: Bearer <your-api-token>\n```\n\nGenerate and rotate the token in the Elai web app under **Settings → API**, or through\n`POST /generateToken`. The token is scoped to one **workspace** and authenticates as that\nworkspace's admin user — it is not tied to an individual person, and it carries admin rights\ninside that workspace.\n\nA request with a missing, unknown or revoked token gets a bare `401` with no response body.\n\n> **Organizations on the Unlimited plan cannot use the API.** Their requests are rejected with the\n> same bare `401` as an invalid token, with nothing to distinguish the two. If a valid, freshly\n> generated token returns `401` on every endpoint, check the plan first.\n\n## Errors\n\nFailures carry a JSON body of the shape `{ \"message\": \"...\" }`. Validation failures on the newer\nendpoints may add an `errors` array naming the offending fields. `401` is the exception: it has no\nbody at all.\n\nBoth render endpoints are **fire-and-forget** — they queue work and return immediately, so a\n`200` means \"accepted\", not \"rendered\". Render failures surface only through the `video_error`\nwebhook, never as an HTTP error on the call that started the render.\n\n## Scope\n\nThis reference is generated from the running code rather than maintained by hand, so it cannot\nquietly fall behind the API it describes. It documents 96 operations across the\n`/api/v1` surface.\n\nEndpoints are grouped by subject in the sidebar. If something you need is missing, or an endpoint\ndoes not behave as described here, tell us.\n\n---\n\n_Generated from `chore/web-4760/api-v1-reference-build` at `5289745d` on 2026-09-04._"
  },
  "servers": [
    {
      "url": "https://apis.elai.io/api/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "bearer",
        "x-default": "SECRET_KEY"
      }
    },
    "schemas": {
      "Upload": {
        "type": "object",
        "description": "A media library asset.",
        "properties": {
          "_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "`image`, `video`, `gif`, `audio`, `frame` or `logo`."
          },
          "status": {
            "type": "string",
            "default": "ready"
          },
          "url": {
            "type": "string",
            "description": "Signed download URL when returned from a list endpoint; the stored path elsewhere."
          },
          "thumbnail": {
            "type": "string",
            "description": "Signed thumbnail URL."
          },
          "size": {
            "type": "string"
          },
          "duration": {
            "type": "number",
            "description": "Seconds, for audio and video."
          },
          "isPrimary": {
            "type": "boolean",
            "description": "True for the workspace's primary logo."
          },
          "brandKitId": {
            "type": "string"
          },
          "uploadFolderId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Containing folder; absent or null at the media-library root."
          },
          "userId": {
            "type": "string"
          },
          "accountId": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/uploads": {
      "get": {
        "tags": [
          "Uploads"
        ],
        "summary": "List media library assets",
        "description": "Lists the workspace's uploaded assets, newest-updated first by default. `frame`, `audio` and `logo` assets are always excluded — use `GET /uploads/frames` and `GET /uploads/music` for those.\n\nWhen no `uploadFolderId`, `q` or `type` filter is given, only assets at the **root** of the media library are returned (those with no folder). Supplying any of those three filters searches across folders instead.\n\nEvery returned `url` and `thumbnail` is a time-limited signed URL — fetch the bytes promptly rather than storing the URL.",
        "parameters": [
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            },
            "description": "Assets to skip."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 30
            },
            "description": "Assets per page. Not capped by the endpoint."
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Case-insensitive substring match on the asset name. Interpreted as a regular expression."
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "images",
                "vectors",
                "videos",
                "gifs"
              ]
            },
            "description": "Asset class. `images` excludes SVGs; `vectors` selects only SVGs. An unrecognised value is ignored rather than rejected."
          },
          {
            "name": "excludeType",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Additional raw `type` value to exclude (on top of `frame`, `audio`, `logo`)."
          },
          {
            "name": "uploadFolderId",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Restrict to one media-library folder."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "CREATED_AT_DESCEND",
                "CREATED_AT_ASCEND",
                "UPDATED_AT_DESCEND",
                "UPDATED_AT_ASCEND",
                "NAME_ASCEND",
                "NAME_DESCEND"
              ],
              "default": "UPDATED_AT_DESCEND"
            },
            "description": "Sort order. An unrecognised value silently falls back to `UPDATED_AT_DESCEND`."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of assets.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "uploads": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Upload"
                      }
                    },
                    "hasMore": {
                      "type": "boolean",
                      "description": "True when more assets match beyond this page."
                    }
                  }
                }
              }
            }
          }
        },
        "operationId": "list-uploads"
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "tags": [
    {
      "name": "Uploads",
      "description": "The media library: images, video, audio and logos."
    }
  ],
  "_id": {
    "buffer": {
      "0": 106,
      "1": 154,
      "2": 229,
      "3": 101,
      "4": 201,
      "5": 178,
      "6": 243,
      "7": 252,
      "8": 223,
      "9": 58,
      "10": 69,
      "11": 151
    }
  }
}
````