CoreViz
API

API Reference

Getting started with the CoreViz Studio API

Getting Started

The CoreViz Studio API gives you programmatic access to your visual library — listing, searching, uploading, and managing media, folders, and tags. All API requests require authentication.

Authentication

All Studio API endpoints accept two authentication methods:

API Key (server-to-server)

Include your API key in the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" \
  https://lab.coreviz.io/api/dataset/COLLECTION_ID/media

Bearer Token (user sessions)

Authenticate with a user session token (obtained via coreviz login or the device auth flow):

curl -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  https://lab.coreviz.io/api/dataset/COLLECTION_ID/media

Getting Your API Key

  1. Navigate to lab.coreviz.io
  2. Go to Your Account → API Keys
  3. Generate or copy an existing key

Base URL

https://lab.coreviz.io/api

Data Structure

CoreViz organizes content in a simple hierarchy:

Organization
└── Collection (dataset)
    ├── Folder  ─────── stored as type=folder in the media table
    │   ├── Media (image / video)
    │   └── Media
    └── Media

Collections

Top-level containers for your media, scoped to an organization. Also referred to internally as dataset. IDs are UUIDs with hyphens stripped (e.g. abc123def456...).

Media

Individual image or video files. Each media item has:

  • File metadata (name, size, dimensions)
  • A path column using the PostgreSQL ltree extension for folder hierarchy
  • A metadata JSONB field containing tags and other attributes
  • Associated frames with AI-generated captions and detected objects

Folders

Folders are type=folder entries in the media table. They appear in browse results alongside regular media items.

Frames

Processed versions of media items. Images have 1 frame; videos have multiple. Frames contain:

  • AI-generated captions
  • Detected objects with bounding boxes and embeddings

Available Endpoints

Collections

MethodEndpointDescription
GET/api/organization/{orgId}/datasetsList collections
POST/api/organization/{orgId}/datasetsCreate collection

Media

MethodEndpointDescription
GET/api/dataset/{id}/mediaBrowse or search media
GET/api/media/{id}Get a single media item
PATCH/api/media/{id}Rename or update metadata
DELETE/api/media/{id}Delete media (soft delete)
PATCH/api/media/{id}/moveMove item to a folder
POST/api/media/{id}/tagsAdd a tag
DELETE/api/media/{id}/tagsRemove a tag

Folders & Tags

MethodEndpointDescription
POST/api/folderCreate a folder
GET/api/dataset/{id}/tagsList tag groups for a collection

Upload

MethodEndpointDescription
POST/api/upload/multipartUpload a media file

Next Steps

Folders & Tags

Create folders to organize media and list tag groups across collections

Browse & Search Media

List and semantically search media items within a collection