Skip to main content
The Aspect REST API gives you programmatic access to everything in your media library: workspaces, projects, directories, assets, collections, search, transcripts, metadata, comments, and share links. All requests go to a single base URL:

​
Authentication

Aspect API keys start with sk_. Send your key in the Authorization header - the Bearer prefix is accepted but optional:
A successful response returns the user who owns the key, which makes GET /users/me a quick way to verify your setup.

​
Creating an API key

1

Open settings

In the Aspect web app, open Settings and go to the API Keys page under your personal settings.
2

Create a key

Click Create new API Key and give it a descriptive name.
3

Copy it immediately

The key value is shown only once at creation time - it cannot be retrieved again. Store it somewhere safe.
An API key acts as you: every request is checked against your own workspace and project permissions. Keep keys out of client-side code and public repositories.
You can also manage keys over the API itself: POST /api-keys creates a key, GET /api-keys lists your keys (metadata only, never the key values), and DELETE /api-keys/{api_key_id} revokes one.

​
Resource model

Everything in Aspect lives in a simple hierarchy:
  • Workspace: the top-level organization unit. Users belong to workspaces.
  • Project: a container inside a workspace that holds directories and assets.
  • Directory: a folder within a project. Directories can nest.
  • Asset: a video, image, audio, or document file that Aspect indexes with AI.
  • Collection: a user-curated grouping of assets and directories within a project.
When an asset is uploaded, Aspect automatically processes it with AI in the background (transcription, visual understanding, instant playback, and more) - there is no processing step to trigger via the API. Permissions are inherited down the tree, so access granted on a project applies to the directories and assets inside it. For a deeper introduction, see Core concepts.

​
Request conventions

  • Request and response bodies are JSON. IDs are UUIDs.
  • Response codes depend on the endpoint. Check the expected status code and response body when integrating an endpoint.
  • Many list endpoints are POST requests with a JSON body rather than GET - for example POST /assets/list and POST /directories/list take a required parent_id plus optional limit, offset, filters, and sorts. Other lists use offset/limit query parameters.
For example, listing the assets in a directory:

​
Uploading and downloading files

Use the Aspect CLI to transfer files from a terminal, script, CI job, or AI agent. On headless machines, supply the same sk_ API key through the ASPECT_API_KEY environment variable; no aspect auth login step is needed. See headless authentication for setup.
Replace the example paths with your own workspace, project, and folders. The upload destination must already exist, and your account must have permission to upload there. Uploads and downloads skip existing filenames by default; use --replace to overwrite them or --keep-both to preserve both copies.
A signed-in Aspect desktop app takes precedence over ASPECT_API_KEY. Use aspect auth status --json to check how the CLI is authenticated. See authentication for desktop and stored-key behavior.
See upload files and download files for transfer details, or scripts and AI agents for JSON output, exit codes, and background jobs.

​
Endpoint reference

The per-endpoint reference is being reworked and will return here soon.

​
Beyond REST

MCP server

Connect Claude, ChatGPT, Cursor, or any MCP client to your Aspect library through our hosted MCP server.