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:

​
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.