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.
  • Successful creates return 201; deletes return 204 with no body.
  • 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. Check each endpoint’s page in the reference below for its exact shape.
For example, listing the assets in a directory:

​
Endpoint reference

The complete, always-current endpoint reference is generated from our OpenAPI schema and lives in the API Endpoints section of this tab’s navigation. It covers every route with request and response schemas.

​
Beyond REST

MCP server

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

Agent API

Drive the Aspect AI assistant programmatically with conversations, streamed events, and tool approvals.