Skip to main content
This guide explains how indexing works in Aspect and how to use the API to:
  • Create an index (a searchable collection of assets)
  • Upload assets (videos, images, audio)
  • Run AI processing (“features”) on those assets
Terminology:
  • index: A collection of assets that are searchable together
  • indexing: The AI processing we run on assets
  • features: Individual processing steps, e.g. proxy, preview, embedding, transcription

​
Authentication

Use the Authorization header with either a user JWT or an API key. Both forms are accepted: 
-H "Authorization: Bearer $ASPECT_API_KEY"

​
Create an index

Indexes define defaults for which features to run when you add assets. 
curl -X POST "$ASPECT_URL/indexes/" \
  -H "Authorization: Bearer $ASPECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "description": "Demo index",
    "default_features": ["proxy", "preview", "embedding", "transcription"],
    "is_sample": false
  }'
Response includes index metadata and defaults.

​
Upload an asset to be indexed

Provide either a direct file upload or a URL to download from. You must include the file name (with extension), the target index_id, and whether to store the original file. File upload example: 
curl -X POST "$ASPECT_URL/assets" \
  -H "Authorization: Bearer $ASPECT_API_KEY" \
  -F index_id="<INDEX_UUID>" \
  -F save_original=true \
  -F name="sample.mp4" \
  -F features=embedding \
  -F features=transcription \
  -F asset_file=@/path/to/sample.mp4
Remote URL example: 
curl -X POST "$ASPECT_URL/assets" \
  -H "Authorization: Bearer $ASPECT_API_KEY" \
  -F index_id="<INDEX_UUID>" \
  -F save_original=false \
  -F name="remote.mp4" \
  -F features=embedding \
  -F asset_url="https://example.com/remote.mp4"
Notes:
  • Send multiple -F features=... fields to request multiple features
  • Name must include an extension; either asset_file or asset_url is required (but not both)

​
Run additional features later (tasks)

You can add more AI processing to an existing asset with tasks. Use feature_types from the core set: proxy, preview, embedding, transcription. 
curl -X POST "$ASPECT_URL/tasks" \
  -H "Authorization: Bearer $ASPECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "<ASSET_UUID>",
    "feature_types": ["embedding", "transcription"]
  }'
Constraints:
  • proxy and preview are created as part of ingestion and cannot be re-requested via tasks

​
Monitor progress and results

  • List active tasks (queued, processing, failed):
curl -X GET "$ASPECT_URL/tasks/active" \
  -H "Authorization: Bearer $ASPECT_API_KEY"
  • Get a specific task:
curl -X GET "$ASPECT_URL/tasks/<TASK_UUID>" \
  -H "Authorization: Bearer $ASPECT_API_KEY"
  • List assets in an index:
curl -X GET "$ASPECT_URL/assets?index_id=<INDEX_UUID>" \
  -H "Authorization: Bearer $ASPECT_API_KEY"
  • Get asset details (includes feature states):
curl -X GET "$ASPECT_URL/assets/<ASSET_UUID>" \
  -H "Authorization: Bearer $ASPECT_API_KEY"
Feature states include: queued, processing, completed, failed, cancelled, na.

​
Download the original file

If the original was stored, you can request a signed download URL: 
curl -X GET "$ASPECT_URL/assets/<ASSET_UUID>/download" \
  -H "Authorization: Bearer $ASPECT_API_KEY"
For complete request/response shapes, see API reference.