Aspect API Reference | Authentication, Media & Search

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:

https://api.aspect.inc

Authentication

Aspect API keys start with sk_. Send your key in the Authorization header - the Bearer prefix is accepted but optional:

curl -H "Authorization: Bearer sk_your_api_key" \
  https://api.aspect.inc/users/me

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

Open settings

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

Create a key

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

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. The app calls directories folders. 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.
Responses may include fields not listed in this reference. Don’t rely on them; they can change without notice.
Response codes depend on the endpoint. Check the expected status code and response body when integrating an endpoint. Failures are described under Errors.
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 for its exact shape.

For example, listing the assets in a directory:

curl -X POST https://api.aspect.inc/assets/list \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"parent_id": "6c8e9a1f-0b0e-4a6a-9c94-1f2d3e4a5b6c", "limit": 50}'

Errors

A failed request returns a standard HTTP status code and a JSON body whose detail field says what went wrong:

{"detail": "Cross-workspace copies are not supported"}

Status	Meaning
`400`	The request is well formed but can’t be carried out, such as copying between workspaces.
`401`	The API key is missing, invalid, or revoked.
`402`	A billing check blocked the request, such as a feature the plan doesn’t include, a plan limit exceeded, or a declined payment when buying a seat. The body has a `code` instead of `detail`, such as `feature_not_entitled`, `limit_exceeded`, or `seat_charge_failed`.
`403`	You don’t have access to the workspace, project, directory, asset, or collection, or it doesn’t exist. Aspect doesn’t reveal whether something you can’t access exists.
`404`	The share, comment, metadata attribute, API key, watermark, job, attachment, or version stack doesn’t exist.
`409`	The request conflicts with existing state, such as a name already taken in the same directory.
`422`	The body or parameters failed validation. `detail` is a list with one entry per problem, as shown below.
`500`	Something failed on our side.

A 422 lists each invalid field:

{
  "detail": [
    {
      "type": "uuid_parsing",
      "loc": ["body", "parent_id"],
      "msg": "Input should be a valid UUID, invalid length: expected length 32 for simple format, found 3",
      "input": "abc",
      "ctx": {"error": "invalid length: expected length 32 for simple format, found 3"}
    }
  ]
}

Every response includes an X-Request-ID header. Include it when you contact support about a failed request.

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.

# ASPECT_API_KEY is supplied by your job runner's secret settings.
aspect upload ./final.mov "aspect://Studio/Client Campaign/Renders" --json
aspect download "aspect://Studio/Client Campaign/Footage" ./footage --json

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

Browse the API Endpoints section of the sidebar for request and response schemas for the documented REST endpoints. Share links for single assets support oEmbed, so tools that understand it (Notion, Slack, WordPress, and others) can turn a pasted share link into an inline player. Share pages advertise the endpoint with a <link rel="alternate" type="application/json+oembed"> discovery tag, and you can call it directly. No API key is needed:

curl "https://api.aspect.inc/shares/oembed?url=https://app.aspect.inc/share/6c8e9a1f-0b0e-4a6a-9c94-1f2d3e4a5b6c&format=json"

The response follows the oEmbed spec: type is video for video assets and rich for everything else, and html is an <iframe> that plays the asset. Pass maxwidth and maxheight to scale the embed down.

Only shares of a single asset embed; folder and collection shares return 404.
Password-protected shares return 401 and cannot be embedded. Inactive or expired shares return 404.
Only format=json is supported.

For embedding from the app (embed codes and link previews), see Embed videos.

Beyond REST

MCP server

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

Authentication

Creating an API key

Resource model

Request conventions

Errors

Uploading and downloading files

Endpoint reference

Embedding share links

Beyond REST

MCP server