> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authenticate with an API key and work with your Aspect workspaces, projects, and assets over REST

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:

```text theme={null}
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:

```bash theme={null}
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

<Steps>
  <Step title="Open settings">
    In the [Aspect web app](https://app.aspect.inc), open **Settings** and go to the **API Keys** page under your personal settings.
  </Step>

  <Step title="Create a key">
    Click **Create new API Key** and give it a descriptive name.
  </Step>

  <Step title="Copy it immediately">
    The key value is shown only once at creation time - it cannot be retrieved again. Store it somewhere safe.
  </Step>
</Steps>

<Note>
  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.
</Note>

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](/docs/concepts/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:

```bash theme={null}
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}'
```

## 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

<CardGroup cols={2}>
  <Card title="MCP server" href="/docs/api-reference/mcp">
    Connect Claude, ChatGPT, Cursor, or any MCP client to your Aspect library through our hosted MCP server.
  </Card>

  <Card title="Agent API" href="/docs/api-reference/agent">
    Drive the Aspect AI assistant programmatically with conversations, streamed events, and tool approvals.
  </Card>
</CardGroup>