### CoreViz SDK Installation

Source: https://github.com/coreviz/sdk/blob/main/README.md

Instructions for installing the CoreViz SDK using npm and specific steps for React Native/Expo environments.

```APIDOC
## CoreViz SDK Installation

### npm
```bash
npm install @coreviz/sdk
```

### React Native / Expo
When using this SDK in Expo / React Native, install the Expo image utilities (used for `resize`):

```bash
npx expo install expo-image-manipulator expo-file-system
```

**Notes:**
- Local mode (`mode: 'local'`) for `tag()` / `embed()` is **not supported** on React Native / Expo.
```

--------------------------------

### Install CoreViz SDK

Source: https://github.com/coreviz/sdk/blob/main/README.md

Install the CoreViz SDK using npm. For React Native/Expo, also install Expo image utilities.

```bash
npm install @coreviz/sdk
```

```bash
npx expo install expo-image-manipulator expo-file-system
```

--------------------------------

### CoreViz SDK Configuration

Source: https://github.com/coreviz/sdk/blob/main/README.md

Examples of how to configure the CoreViz SDK client for different environments, including API key, session token, and self-hosted options.

```APIDOC
## CoreViz SDK Configuration

```typescript
import { CoreViz } from '@coreviz/sdk';

// External use — API key
const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// CLI / server — session token
const coreviz = new CoreViz({ token: 'your_session_token' });

// Self-hosted or local dev — override base URL
const coreviz = new CoreViz({ apiKey: '...', baseUrl: 'http://localhost:3000' });

// Browser same-origin — no credentials needed; session cookie is used automatically
const coreviz = new CoreViz({ baseUrl: window.location.origin });
```
```

--------------------------------

### coreviz.generate

Source: https://github.com/coreviz/sdk/blob/main/README.md

Generates an image from a text prompt, optionally guided by reference images.

```APIDOC
## POST /coreviz/generate

### Description
Generates an image from a text prompt, optionally guided by reference images.

### Method
POST

### Endpoint
/coreviz/generate

### Parameters
#### Request Body
- **prompt** (string) - Required - Text description.
- **options** (object) - Optional
  - **referenceImages** (string[]) - Optional - Reference images (URL/base64) to guide style or structure.
  - **aspectRatio** (string) - Optional - e.g. '1:1', '16:9', '4:3'.
  - **model** (string) - Optional - 'google/nano-banana' | 'google/nano-banana-pro' | 'seedream-4' | 'flux-kontext-max'. Default: 'google/nano-banana-pro'.

### Response
#### Success Response (200)
- **string** (string) - generated image URL.

### Request Example
```json
{
  "prompt": "A futuristic city at dusk",
  "options": {
    "aspectRatio": "16:9"
  }
}
```

### Response Example
```json
{
  "imageUrl": "https://example.com/generated_image.png"
}
```
```

--------------------------------

### Manage Folders in CoreViz SDK

Source: https://context7.com/coreviz/sdk/llms.txt

This snippet demonstrates how to create, get, update, and delete folders within collections using the CoreViz SDK. Folders are organized using ltree paths. The `create` method supports an `upsert` option to prevent duplicate entries.

```typescript
import { CoreViz } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_API_KEY });

// Create folder at collection root
const folder = await coreviz.folders.create('col_123', 'Spring 2025');
console.log(folder);
// { id: 'folder_abc', name: 'Spring 2025', path: 'col_123.folder_abc', collectionId: 'col_123' }

// Create nested folder
const subFolder = await coreviz.folders.create('col_123', 'Products', 'col_123.folder_abc');

// Create with upsert (returns existing if name matches)
const importFolder = await coreviz.folders.create('col_123', 'Imports', undefined, true);
// Safe to call repeatedly - won't create duplicates

// Get folder details
const folderDetails = await coreviz.folders.get('folder_abc');

// Update folder
const updated = await coreviz.folders.update('folder_abc', {
  name: 'Spring Campaign 2025',
  metadata: { status: 'active', assignee: 'marketing' },
});

// Delete folder and all contents
await coreviz.folders.delete('folder_abc');
```

--------------------------------

### Get, Rename, Move, and Delete Media Items with CoreViz SDK

Source: https://context7.com/coreviz/sdk/llms.txt

Use these methods to manage individual media items. Ensure you have the correct media ID and collection ID for operations. Retrieving an item provides access to its metadata, dimensions, and detected objects.

```typescript
import { CoreViz } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// Get full media details
const item = await coreviz.media.get('media_123');
console.log({
  id: item.id,
  name: item.name,
  type: item.type,
  url: item.blob,
  dimensions: `${item.width}x${item.height}`,
  size: item.sizeBytes,
  metadata: item.metadata,
  frames: item.frames?.length, // Video frames with detected objects
  created: item.createdAt,
});

// Access detected objects from frames
item.frames?.forEach(frame => {
  console.log(`Frame at ${frame.timestamp}s:`, frame.objects.map(o => o.label));
});

// Rename media item
const renamed = await coreviz.media.rename('media_123', 'hero-shot-final.jpg');

// Move to different folder
const { id, newPath } = await coreviz.media.move('media_123', 'col_123.archive_folder');
console.log(`Moved to: ${newPath}`);

// Delete media permanently
await coreviz.media.delete('media_123');
```

--------------------------------

### Generate Image from Prompt

Source: https://github.com/coreviz/sdk/blob/main/README.md

Generates an image from a text prompt, optionally guided by reference images and aspect ratio. Supports various models for image generation.

```typescript
const image = await coreviz.generate('A futuristic city at dusk', { aspectRatio: '16:9' });
```

--------------------------------

### Get Current User Context

Source: https://github.com/coreviz/sdk/blob/main/README.md

Retrieves information about the currently authenticated user and their default organization. Requires authentication.

```typescript
const { name, email, organizationId } = await coreviz.me();
```

--------------------------------

### AI Image Generation

Source: https://context7.com/coreviz/sdk/llms.txt

Generate images from text prompts, optionally guided by reference images for style or structure. Supports multiple aspect ratios and AI models.

```APIDOC
## AI Image Generation

### Description
Generate images from text prompts, optionally guided by reference images for style or structure. Supports multiple aspect ratios and AI models including google/nano-banana-pro, seedream-4, and flux-kontext-max.

### Method
POST (assumed, based on SDK usage)

### Endpoint
/v1/images/generate (assumed)

### Parameters
#### Request Body
- **prompt** (string) - Required - The text prompt to generate an image from.
- **aspectRatio** (string) - Optional - The desired aspect ratio (e.g., '16:9', '3:2', '4:3').
- **model** (string) - Optional - The AI model to use for generation (e.g., 'google/nano-banana-pro', 'seedream-4', 'flux-kontext-max').
- **referenceImages** (array of strings) - Optional - URLs of reference images for style or structure guidance.

### Request Example
```json
{
  "prompt": "A futuristic city at dusk with neon lights",
  "aspectRatio": "16:9",
  "model": "google/nano-banana-pro"
}
```

### Request Example (with reference images)
```json
{
  "prompt": "A mountain landscape",
  "referenceImages": [
    "https://example.com/style-reference.jpg",
    "https://example.com/composition-reference.jpg"
  ],
  "aspectRatio": "3:2"
}

### Response
#### Success Response (200)
- **imageUrl** (string) - URL of the generated image.

### Response Example
```json
{
  "imageUrl": "https://cdn.coreviz.io/images/generated/abc123xyz.jpg"
}
```
```

--------------------------------

### Get Folder by ID

Source: https://github.com/coreviz/sdk/blob/main/README.md

Retrieves a specific folder using its unique ID. This is useful for accessing folder details or checking its existence.

```typescript
const folder = await coreviz.folders.get('folderId123');
```

--------------------------------

### Get Media Item Details

Source: https://github.com/coreviz/sdk/blob/main/README.md

Retrieve full details for a specific media item, including its blob URL, dimensions, metadata, detected objects, and frames. Requires the media item's ID.

```typescript
const item = await coreviz.media.get('mediaId123');
console.log(item.blob, item.metadata?.tags, item.frames);
```

--------------------------------

### Tag Image with CoreViz SDK

Source: https://github.com/coreviz/sdk/blob/main/README.md

Analyze an image to get tags or classifications based on a prompt. You can provide specific options to restrict answers and choose whether to allow multiple tags. The 'mode' option allows for local, in-browser processing.

```typescript
const { tags } = await coreviz.tag(imageUrl, {
  prompt: 'Is this indoor or outdoor?',
  options: ['indoor', 'outdoor'],
  multiple: false,
});
```

--------------------------------

### Media Item Operations

Source: https://context7.com/coreviz/sdk/llms.txt

Operations for getting, renaming, moving, and deleting individual media items. Retrieve full details including blob URLs, dimensions, metadata, detected objects, and video frames.

```APIDOC
## Media Item Operations

### Description
Get, rename, move, and delete individual media items. Retrieve full details including blob URLs, dimensions, metadata, detected objects, and video frames.

### Method
- GET: `coreviz.media.get(itemId)`
- POST: `coreviz.media.rename(itemId, newName)`
- POST: `coreviz.media.move(itemId, destinationPath)`
- DELETE: `coreviz.media.delete(itemId)`

### Parameters
#### Path Parameters
- **itemId** (string) - Required - The unique identifier for the media item.
- **newName** (string) - Required - The new name for the media item.
- **destinationPath** (string) - Required - The path to the destination folder for moving the media item.

### Response
#### Success Response (200)
- **item** (object) - Details of the media item, including id, name, type, blob URL, dimensions, size, metadata, and frames.
- **renamed** (object) - Confirmation of the rename operation.
- **moveResult** (object) - Contains `id` and `newPath` upon successful move.
- **deleteResult** (string) - Confirmation message upon successful deletion.

#### Response Example (Get)
```json
{
  "id": "media_123",
  "name": "example.jpg",
  "type": "image",
  "blob": "https://...",
  "width": 1920,
  "height": 1080,
  "sizeBytes": 1024000,
  "metadata": {},
  "frames": [],
  "createdAt": "2023-01-01T10:00:00Z"
}
```
```

--------------------------------

### Configure CoreViz SDK Client

Source: https://github.com/coreviz/sdk/blob/main/README.md

Instantiate the CoreViz client with an API key for external use, a session token for CLI/server, or override the base URL for self-hosted instances. Browser same-origin usage does not require credentials.

```typescript
import { CoreViz } from '@coreviz/sdk';

// External use — API key
const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// CLI / server — session token
const coreviz = new CoreViz({ token: 'your_session_token' });

// Self-hosted or local dev — override base URL
const coreviz = new CoreViz({ apiKey: '...', baseUrl: 'http://localhost:3000' });

// Browser same-origin — no credentials needed; session cookie is used automatically
const coreviz = new CoreViz({ baseUrl: window.location.origin });
```

--------------------------------

### Get Collection Details

Source: https://context7.com/coreviz/sdk/llms.txt

Retrieves the details of a specific collection using its ID. Ensure the collection ID is valid.

```typescript
const collection = await coreviz.collections.get('col_123');
console.log(collection.name);
```

--------------------------------

### SDK Initialization

Source: https://context7.com/coreviz/sdk/llms.txt

Initialize the CoreViz client with your preferred authentication method. The SDK supports API keys, session tokens, or browser session cookies.

```APIDOC
## SDK Initialization

Initialize the CoreViz client with your preferred authentication method. The SDK supports API keys for external use, session tokens for CLI/server contexts, and automatic session cookie handling for browser same-origin requests.

### Request Example
```typescript
import { CoreViz } from '@coreviz/sdk';

// External use with API key
const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// CLI / server with session token
const coreviz = new CoreViz({ token: 'your_session_token' });

// Self-hosted or local development with custom base URL
const coreviz = new CoreViz({ apiKey: 'your_api_key', baseUrl: 'http://localhost:3000' });

// Browser same-origin (session cookie used automatically)
const coreviz = new CoreViz({ baseUrl: window.location.origin });
```
```

--------------------------------

### coreviz.media.browse

Source: https://github.com/coreviz/sdk/blob/main/README.md

Lists media and folders within a collection, supporting various filters, search, and similarity queries.

```APIDOC
## coreviz.media.browse(collectionId, options?)

### Description
List media and folders inside a collection. Supports browsing, filtering, searching, and similarity queries all through the same method.

### Method
GET

### Endpoint
/coreviz/sdk

### Parameters
#### Query Parameters
- **collectionId** (string) - Required - The ID of the collection to browse.
- **path** (string) - Optional - ltree path to list (e.g. "collId.folderId"). Defaults to collection root.
- **limit** (number) - Optional - Pagination limit.
- **offset** (number) - Optional - Pagination offset.
- **type** ('image' | 'video' | 'folder' | 'all') - Optional - Filter by media type.
- **dateFrom** (string) - Optional - Date range filter (YYYY-MM-DD).
- **dateTo** (string) - Optional - Date range filter (YYYY-MM-DD).
- **sortBy** (string) - Optional - Sort field.
- **sortDirection** ('asc' | 'desc') - Optional - Sort direction.
- **tagFilters** (Record<string, string[]>) - Optional - AND between groups, OR within group.
- **q** (string) - Optional - Text/semantic search query (triggers scored mode).
- **similarToObjectId** (string) - Optional - Find visually similar media by detected object ID.
- **similarToObjectModel** (string) - Optional - Vision model for similarity scoring.
- **tags** (string) - Optional - Comma-separated tag label filter.
- **mediaId** (string) - Optional - Filter to a specific media item.
- **clusterId** (string) - Optional - Filter to a specific object cluster.
- **recursive** (boolean) - Optional - List all descendants recursively (flattened view).

### Response
#### Success Response (200)
- **media** (Media[]) - Array of media items.
- **pagination** (object) - Pagination details.

### Request Example
```typescript
// Browse a folder
const { media } = await coreviz.media.browse('collId', { path: 'collId.folderXyz', limit: 50 });

// In-folder semantic search
const { media: results } = await coreviz.media.browse('collId', { q: 'red shoes' });

// Find similar media by object
const { media: similar } = await coreviz.media.browse('collId', { similarToObjectId: 'objId' });
```
```

--------------------------------

### Get Single Collection by ID

Source: https://github.com/coreviz/sdk/blob/main/README.md

Retrieves a specific collection using its unique identifier. Returns a Promise that resolves to the Collection object.

```typescript
const collection = await coreviz.collections.get('abc123');
```

--------------------------------

### coreviz.collections.create

Source: https://github.com/coreviz/sdk/blob/main/README.md

Creates a new collection.

```APIDOC
## POST /coreviz/collections

### Description
Create a new collection.

### Method
POST

### Endpoint
/coreviz/collections

### Parameters
#### Request Body
- **name** (string) - Required - The name of the new collection.
- **icon** (string) - Optional - An icon for the collection.
- **organizationId** (string) - Optional - Target organization. Defaults to the current user's organization.

### Response
#### Success Response (200)
- **collection** (object) - The newly created collection object.

### Request Example
```json
{
  "name": "Product Photos",
  "icon": "📦"
}
```

### Response Example
```json
{
  "collection": {
    "id": "coll_new_123",
    "name": "Product Photos",
    "icon": "📦"
  }
}
```
```

--------------------------------

### Manage Media Versions with CoreViz SDK

Source: https://context7.com/coreviz/sdk/llms.txt

Track and manage different versions of a media item, often created by AI edits. Use `listVersions` to see history, `selectVersion` to activate a specific one, and `deleteVersion` to remove an old version.

```typescript
import { CoreViz } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// List all versions of a media item
const versions = await coreviz.media.listVersions('media_123');
versions.forEach(v => {
  console.log({
    id: v.id,
    name: v.name,
    url: v.blob,
    created: v.createdAt,
  });
});

// Select a specific version as active
await coreviz.media.selectVersion('version_456');

// Delete a version (auto-promotes another if deleted was active)
const { deletedId, promotedId } = await coreviz.media.deleteVersion('media_123', 'version_789');
if (promotedId) {
  console.log(`Version ${deletedId} deleted, ${promotedId} promoted to active`);
}
```

--------------------------------

### coreviz.media.get

Source: https://github.com/coreviz/sdk/blob/main/README.md

Retrieves full details for a specific media item.

```APIDOC
## coreviz.media.get(mediaId)

### Description
Get full details for a media item including blob URL, dimensions, metadata, detected objects, and frames.

### Method
GET

### Endpoint
/coreviz/sdk

### Parameters
#### Path Parameters
- **mediaId** (string) - Required - The ID of the media item.

### Response
#### Success Response (200)
- **Media** - Object containing media details like `blob`, `metadata`, `frames`.

### Request Example
```typescript
const item = await coreviz.media.get('mediaId123');
console.log(item.blob, item.metadata?.tags, item.frames);
```
```

--------------------------------

### Initialize CoreViz Client

Source: https://context7.com/coreviz/sdk/llms.txt

Initialize the CoreViz client using an API key, session token, or automatically with browser session cookies for same-origin requests. A custom base URL can be provided for self-hosted or local development.

```typescript
import { CoreViz } from '@coreviz/sdk';

// External use with API key
const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// CLI / server with session token
const coreviz = new CoreViz({ token: 'your_session_token' });

// Self-hosted or local development with custom base URL
const coreviz = new CoreViz({ apiKey: 'your_api_key', baseUrl: 'http://localhost:3000' });

// Browser same-origin (session cookie used automatically)
const coreviz = new CoreViz({ baseUrl: window.location.origin });
```

--------------------------------

### Select Media Version

Source: https://github.com/coreviz/sdk/blob/main/README.md

Marks a specific version of a media item as the active or current version. This is useful for reverting to or highlighting a particular state of the media.

```typescript
await coreviz.media.selectVersion('versionId456');
```

--------------------------------

### Find Visually Similar Media with CoreViz SDK

Source: https://context7.com/coreviz/sdk/llms.txt

Use this snippet to find media visually similar to a given object ID. It supports different vision models for various similarity types. Ensure the CoreViz SDK is initialized with an API key.

```typescript
import { CoreViz } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_API_KEY });

// Get media with detected objects
const item = await coreviz.media.get('media_123');
const faceObject = item.frames?.[0]?.objects.find(o => o.type === 'face');

// Find similar faces in collection
if (faceObject) {
  const { media: similarFaces } = await coreviz.media.findSimilar('col_123', faceObject.id, {
    model: 'faces',
    limit: 20,
  });
  console.log(`Found ${similarFaces.length} similar faces`);
}

// Find similar objects
const productObject = item.frames?.[0]?.objects.find(o => o.type === 'object');
if (productObject) {
  const { media: similarProducts } = await coreviz.media.findSimilar('col_123', productObject.id, {
    model: 'objects',
    limit: 50,
  });
}
```

--------------------------------

### List Collections

Source: https://context7.com/coreviz/sdk/llms.txt

Fetches collections within the default organization or a specified organization. Requires an initialized CoreViz client.

```typescript
import { CoreViz } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// List all collections in default organization
const collections = await coreviz.collections.list();
console.log(collections);
```

```typescript
const orgCollections = await coreviz.collections.list('org_xyz789');
```

--------------------------------

### Browse Media by Folder Path

Source: https://context7.com/coreviz/sdk/llms.txt

Browses media items within a specific folder path inside a collection. Use the 'path' option with the collection ID.

```typescript
const { media: folderMedia } = await coreviz.media.browse('col_123', {
  path: 'col_123.folder_abc',
  limit: 100,
});
```

--------------------------------

### Describe Image with CoreViz SDK

Source: https://github.com/coreviz/sdk/blob/main/README.md

Generate a detailed text description for an image using its URL. The image parameter can be a Base64 data URL or a remote URL.

```typescript
const description = await coreviz.describe('https://example.com/image.jpg');
```

--------------------------------

### Browse Media with Pagination

Source: https://context7.com/coreviz/sdk/llms.txt

Performs basic media browsing within a collection, including pagination controls. Specify the collection ID and pagination options like limit and offset.

```typescript
const { media, pagination } = await coreviz.media.browse('col_123', {
  limit: 50,
  offset: 0,
});
console.log(`Showing ${media.length} of ${pagination.total} items`);
```

--------------------------------

### Browse Media by Type and Sort

Source: https://context7.com/coreviz/sdk/llms.txt

Filters media items by type (e.g., 'image') and sorts them by creation date in descending order. Requires collection ID and filter/sort options.

```typescript
const { media: images } = await coreviz.media.browse('col_123', {
  type: 'image',
  sortBy: 'createdAt',
  sortDirection: 'desc',
});
```

--------------------------------

### Browse Media in a Collection

Source: https://github.com/coreviz/sdk/blob/main/README.md

List media and folders within a collection. Supports filtering by path, type, date range, tags, and recursive listing. Use for browsing, filtering, and searching.

```typescript
const { media } = await coreviz.media.browse('collId', { path: 'collId.folderXyz', limit: 50 });
```

```typescript
const { media: results } = await coreviz.media.browse('collId', { q: 'red shoes' });
```

```typescript
const { media: similar } = await coreviz.media.browse('collId', { similarToObjectId: 'objId' });
```

--------------------------------

### Generate AI Images with CoreViz SDK

Source: https://context7.com/coreviz/sdk/llms.txt

Generate images from text prompts, optionally using reference images for style or structure. Supports various aspect ratios and AI models. Requires an API key.

```typescript
import { CoreViz } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// Generate from text prompt
const image = await coreviz.generate('A futuristic city at dusk with neon lights', {
  aspectRatio: '16:9',
  model: 'google/nano-banana-pro',
});
console.log(image); // Returns generated image URL

// Generate with reference images for style guidance
const styledImage = await coreviz.generate('A mountain landscape', {
  referenceImages: [
    'https://example.com/style-reference.jpg',
    'https://example.com/composition-reference.jpg',
  ],
  aspectRatio: '3:2',
});

// Generate product mockup
const mockup = await coreviz.generate('A minimalist product photo of a smartphone on marble', {
  aspectRatio: '4:3',
  model: 'seedream-4',
});
```

--------------------------------

### List Media Versions

Source: https://github.com/coreviz/sdk/blob/main/README.md

Retrieves all versions of a specific media item, including the original and all AI-edited derivatives. Use this to access the edit history of a media asset.

```typescript
const versions = await coreviz.media.listVersions('mediaId123');
```

--------------------------------

### Media Versions API

Source: https://github.com/coreviz/sdk/blob/main/README.md

Manage and retrieve different versions of media items.

```APIDOC
## GET /coreviz/sdk/media/listVersions

### Description
List all versions of a media item (original + all AI-edited derivatives).

### Method
GET

### Endpoint
`/coreviz/sdk/media/listVersions(mediaId)`

### Parameters
#### Path Parameters
- **mediaId** (string) - Required - The ID of the media item.

### Response
#### Success Response (200)
- **Media[]** (array) - An array of media version objects.

### Request Example
```typescript
const versions = await coreviz.media.listVersions('mediaId123');
```
```

```APIDOC
## PUT /coreviz/sdk/media/selectVersion

### Description
Mark a version as the active/current version.

### Method
PUT

### Endpoint
`/coreviz/sdk/media/selectVersion(versionId)`

### Parameters
#### Path Parameters
- **versionId** (string) - Required - The ID of the version to select as active.

### Request Example
```typescript
await coreviz.media.selectVersion('versionId456');
```
```

```APIDOC
## DELETE /coreviz/sdk/media/deleteVersion

### Description
Delete a specific version. If the deleted version was active, the server promotes another version automatically.

### Method
DELETE

### Endpoint
`/coreviz/sdk/media/deleteVersion(rootMediaId, versionId)`

### Parameters
#### Path Parameters
- **rootMediaId** (string) - Required - The ID of the root media item.
- **versionId** (string) - Required - The ID of the version to delete.

### Response
#### Success Response (200)
- **deletedId** (string) - The ID of the deleted version.
- **promotedId** (string | null) - The ID of the promoted version, or null if no version was promoted.

### Request Example
```typescript
const { promotedId } = await coreviz.media.deleteVersion('rootMediaId', 'versionId456');
if (promotedId) {
  // navigate to promoted version
}
```
```

--------------------------------

### coreviz.baseUrl

Source: https://github.com/coreviz/sdk/blob/main/README.md

The API base URL this instance is configured to use.

```APIDOC
## GET /coreviz/baseUrl

### Description
The API base URL this instance is configured to use (read-only getter).

### Method
GET

### Endpoint
/coreviz/baseUrl

### Response
#### Success Response (200)
- **baseUrl** (string) - The API base URL.

### Response Example
```json
{
  "baseUrl": "https://lab.coreviz.io"
}
```
```

--------------------------------

### List Organizations

Source: https://context7.com/coreviz/sdk/llms.txt

Fetches a list of all organizations the current user belongs to. Ensure the COREVIZ_API_KEY is set in your environment variables.

```typescript
import { CoreViz } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

const organizations = await coreviz.organizations.list();
console.log(organizations);
```

--------------------------------

### Browse Media by Tags

Source: https://context7.com/coreviz/sdk/llms.txt

Filters media items based on multiple tags across different categories. Use 'tagFilters' with an object where keys are tag categories and values are arrays of tags.

```typescript
const { media: taggedMedia } = await coreviz.media.browse('col_123', {
  tagFilters: { color: ['red', 'blue'], category: ['product'] },
});
```

--------------------------------

### Recursive Media Listing

Source: https://context7.com/coreviz/sdk/llms.txt

Lists all media items recursively within a collection and its subfolders. Set the 'recursive' option to true.

```typescript
const { media: allMedia } = await coreviz.media.browse('col_123', {
  recursive: true,
});
```

--------------------------------

### coreviz.me

Source: https://github.com/coreviz/sdk/blob/main/README.md

Returns the current authenticated user and their default organization.

```APIDOC
## GET /coreviz/me

### Description
Return the current authenticated user and their default organization.

### Method
GET

### Endpoint
/coreviz/me

### Response
#### Success Response (200)
- **userId** (string) - The ID of the user.
- **email** (string) - The email address of the user.
- **name** (string) - The name of the user.
- **organizationId** (string) - The ID of the user's default organization.
- **organizationName** (string) - The name of the user's default organization.

### Response Example
```json
{
  "userId": "user_abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "organizationId": "org_xyz789",
  "organizationName": "Example Corp"
}
```
```

--------------------------------

### coreviz.media.addTag

Source: https://github.com/coreviz/sdk/blob/main/README.md

Adds a tag to a media item.

```APIDOC
## coreviz.media.addTag(mediaId, label, value)

### Description
Add a tag to a media item. Tags are `label` (group) + `value` pairs.

### Method
POST

### Endpoint
/coreviz/sdk

### Parameters
#### Path Parameters
- **mediaId** (string) - Required - The ID of the media item.
- **label** (string) - Required - The tag label (group).
- **value** (string) - Required - The tag value.

### Request Example
```typescript
await coreviz.media.addTag('mediaId123', 'color', 'red');
```
```

--------------------------------

### Folders API

Source: https://github.com/coreviz/sdk/blob/main/README.md

Manage folders within collections for organizing media.

```APIDOC
## POST /coreviz/sdk/folders/create

### Description
Create a new folder inside a collection.

### Method
POST

### Endpoint
`/coreviz/sdk/folders/create(collectionId, name, path?, reuse?)

### Parameters
#### Path Parameters
- **collectionId** (string) - Required - The ID of the collection where the folder will be created.
- **name** (string) - Required - The name of the new folder.
- **path** (string) - Optional - The parent ltree path for the new folder. Defaults to the collection root.
- **reuse** (boolean) - Optional - If true, returns the existing folder if one with the same name already exists at that path (upsert behavior).

### Response
#### Success Response (200)
- **Folder** (object) - The created or existing folder object.

### Request Example
```typescript
const folder = await coreviz.folders.create('collId', 'Spring 2025', 'collId.campaigns');

// Upsert — safe to call repeatedly
const folder = await coreviz.folders.create('collId', 'Imports', undefined, true);
```
```

```APIDOC
## GET /coreviz/sdk/folders/get

### Description
Get a folder by its ID.

### Method
GET

### Endpoint
`/coreviz/sdk/folders/get(folderId)`

### Parameters
#### Path Parameters
- **folderId** (string) - Required - The ID of the folder to retrieve.

### Response
#### Success Response (200)
- **Folder** (object) - The folder object.

### Request Example
```typescript
const folder = await coreviz.folders.get('folderId123');
```
```

```APIDOC
## PUT /coreviz/sdk/folders/update

### Description
Update a folder's name or metadata.

### Method
PUT

### Endpoint
`/coreviz/sdk/folders/update(folderId, updates)`

### Parameters
#### Path Parameters
- **folderId** (string) - Required - The ID of the folder to update.

#### Request Body
- **updates** (object) - Required - An object containing the updates to apply. 
  - **name** (string) - Optional - The new name for the folder.
  - **metadata** (Record<string, unknown>) - Optional - An object containing metadata key-value pairs to update.

### Response
#### Success Response (200)
- **Folder** (object) - The updated folder object.

### Request Example
```typescript
await coreviz.folders.update('folderId123', { name: 'Archived Campaign' });
```
```

```APIDOC
## DELETE /coreviz/sdk/folders/delete

### Description
Delete a folder and all its contents.

### Method
DELETE

### Endpoint
`/coreviz/sdk/folders/delete(folderId)`

### Parameters
#### Path Parameters
- **folderId** (string) - Required - The ID of the folder to delete.

### Request Example
```typescript
await coreviz.folders.delete('folderId123');
```
```

--------------------------------

### Manage Media Tags with CoreViz SDK

Source: https://context7.com/coreviz/sdk/llms.txt

Add, remove, and manage tags on media items. Tags are key-value pairs (label and value) for structured categorization. Use `removeTag` for specific values and `removeTagGroup` for entire categories.

```typescript
import { CoreViz } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// Add tags to media
await coreviz.media.addTag('media_123', 'color', 'red');
await coreviz.media.addTag('media_123', 'color', 'blue');
await coreviz.media.addTag('media_123', 'category', 'product');
await coreviz.media.addTag('media_123', 'season', 'summer');

// Remove specific tag value
await coreviz.media.removeTag('media_123', 'color', 'blue');

// Remove entire tag group (all values under label)
await coreviz.media.removeTagGroup('media_123', 'season');

// Rename tag group (preserves all values)
await coreviz.media.renameTagGroup('media_123', 'colour', 'color');

// List all tags in a collection
const tags = await coreviz.tags.list('col_123');
console.log(tags);
// { color: ['red', 'blue', 'green'], category: ['product', 'lifestyle'] }
```

--------------------------------

### Browse Media by Date Range

Source: https://context7.com/coreviz/sdk/llms.txt

Filters media items within a specified date range. Provide 'dateFrom' and 'dateTo' in 'YYYY-MM-DD' format.

```typescript
const { media: recentMedia } = await coreviz.media.browse('col_123', {
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31',
});
```

--------------------------------

### coreviz.media.move

Source: https://github.com/coreviz/sdk/blob/main/README.md

Moves a media item to a different folder within the same collection.

```APIDOC
## coreviz.media.move(mediaId, destinationPath)

### Description
Move a media item to a different folder within the same collection.

### Method
PUT

### Endpoint
/coreviz/sdk

### Parameters
#### Path Parameters
- **mediaId** (string) - Required - The ID of the media item to move.
- **destinationPath** (string) - Required - ltree path of the destination folder.

### Response
#### Success Response (200)
- **{ id, newPath }** - Object containing the media ID and its new path.

### Request Example
```typescript
await coreviz.media.move('mediaId123', 'collId.archiveFolder');
```
```

--------------------------------

### coreviz.media.rename

Source: https://github.com/coreviz/sdk/blob/main/README.md

Renames a media item.

```APIDOC
## coreviz.media.rename(mediaId, name)

### Description
Rename a media item.

### Method
PUT

### Endpoint
/coreviz/sdk

### Parameters
#### Path Parameters
- **mediaId** (string) - Required - The ID of the media item to rename.
- **name** (string) - Required - The new name for the media item.

### Response
#### Success Response (200)
- **Media** - The updated media item object.

### Request Example
```typescript
await coreviz.media.rename('mediaId123', 'hero-shot-final.jpg');
```
```

--------------------------------

### coreviz.collections.list

Source: https://github.com/coreviz/sdk/blob/main/README.md

Lists all collections in an organization.

```APIDOC
## GET /coreviz/collections

### Description
List all collections in an organization.

### Method
GET

### Endpoint
/coreviz/collections

### Parameters
#### Query Parameters
- **organizationId** (string) - Optional - Pass explicitly to skip the `/api/me` round-trip.

### Response
#### Success Response (200)
- **collections** (array) - An array of collection objects.

### Response Example
```json
{
  "collections": [
    { "id": "coll_1", "name": "Product Photos" },
    { "id": "coll_2", "name": "Marketing Assets" }
  ]
}
```
```

--------------------------------

### Resize Images with CoreViz SDK

Source: https://context7.com/coreviz/sdk/llms.txt

Resize images client-side using canvas or server-side using Sharp. Maintains aspect ratio and fits within specified dimensions. Can be used via an instance method or a standalone function. Returns a base64 data URL.

```typescript
import { CoreViz, resize } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// Resize via instance method
const resized = await coreviz.resize('https://example.com/large-image.jpg', 800, 600);
console.log(resized); // base64 data URL

// Standalone resize function
const thumbnail = await resize(imageFile, 200, 200);

// Resize File object (browser)
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
const resizedFile = await resize(file, 1024, 1024);

// Default dimensions (1920x1080)
const defaultResized = await resize(imageUrl);
```

--------------------------------

### coreviz.media.upload

Source: https://github.com/coreviz/sdk/blob/main/README.md

Uploads a photo or video to a specified collection and path.

```APIDOC
## coreviz.media.upload(file, options)

### Description
Upload a photo or video.

### Method
POST

### Endpoint
/coreviz/sdk

### Parameters
#### Request Body
- **file** (string | File | Blob) - Required - Local file path string (Node.js), `File` (browser), or `Blob`.
- **options** (object) - Required - Upload options.
  - **collectionId** (string) - Required - The ID of the collection to upload to.
  - **path** (string) - Optional - Destination ltree folder path.
  - **name** (string) - Optional - Override stored file name.

### Response
#### Success Response (200)
- **UploadResult** - Object containing `mediaId`, `url`, `message`.

### Request Example
```typescript
// Node.js
const result = await coreviz.media.upload('/path/to/photo.jpg', { collectionId: 'abc123' });

// Browser
const result = await coreviz.media.upload(file, { collectionId: 'abc123', path: 'abc123.folder' });
```
> File path strings are not supported on React Native / Expo. Pass a `File` or `Blob` instead.
```

--------------------------------

### Create Collection

Source: https://context7.com/coreviz/sdk/llms.txt

Creates a new collection with a specified name and optional icon, within the default or a specified organization. The organization ID is optional.

```typescript
const newCollection = await coreviz.collections.create('Campaign Assets 2025', '🎯');
console.log(newCollection.id);
```

```typescript
const orgCollection = await coreviz.collections.create('Marketing', '📢', 'org_xyz789');
```

--------------------------------

### Create Folder

Source: https://github.com/coreviz/sdk/blob/main/README.md

Creates a new folder within a specified collection. You can optionally provide a parent path and set `reuse` to true for upsert behavior, which returns an existing folder if one with the same name already exists at the specified path.

```typescript
const folder = await coreviz.folders.create('collId', 'Spring 2025', 'collId.campaigns');

// Upsert — safe to call repeatedly
const folder = await coreviz.folders.create('collId', 'Imports', undefined, true);
```

--------------------------------

### Browse Media by Semantic Search

Source: https://context7.com/coreviz/sdk/llms.txt

Performs a semantic search within a collection using a natural language query. Use the 'q' parameter for the search query.

```typescript
const { media: searchResults } = await coreviz.media.browse('col_123', {
  q: 'red sneakers on white background',
});
```

--------------------------------

### Media Browsing and Listing API

Source: https://context7.com/coreviz/sdk/llms.txt

Endpoints for browsing and listing media items within collections, with support for various filters and search options.

```APIDOC
## Media Browsing and Listing

### Description
Browse and list media items within collections. Supports filtering by type, date range, tags, pagination, sorting, and semantic search queries.

### Method
GET

### Endpoint
/media/browse/{collectionId}

### Parameters
#### Path Parameters
- **collectionId** (string) - Required - The ID of the collection to browse.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of items to return.
- **offset** (integer) - Optional - The number of items to skip (for pagination).
- **path** (string) - Optional - The path to a specific folder within the collection.
- **type** (string) - Optional - Filter media by type (e.g., 'image', 'video').
- **sortBy** (string) - Optional - Field to sort by (e.g., 'createdAt').
- **sortDirection** (string) - Optional - Direction of sorting ('asc' or 'desc').
- **dateFrom** (string) - Optional - Filter media created on or after this date (YYYY-MM-DD).
- **dateTo** (string) - Optional - Filter media created on or before this date (YYYY-MM-DD).
- **tagFilters** (object) - Optional - Filters based on tags. Example: `{ color: ['red', 'blue'], category: ['product'] }`.
- **q** (string) - Optional - Semantic search query string.
- **similarToObjectId** (string) - Optional - Find media similar to a specific object ID.
- **similarToObjectModel** (string) - Optional - The model of the object to find similar media for.
- **recursive** (boolean) - Optional - Whether to list all descendants recursively.

### Request Example
```typescript
import { CoreViz } from '@coreviz/sdk';

const coreviz = new CoreViz({ apiKey: process.env.COREVIZ_API_KEY });

// Basic browsing with pagination
const { media, pagination } = await coreviz.media.browse('col_123', {
  limit: 50,
  offset: 0,
});
console.log(`Showing ${media.length} of ${pagination.total} items`);

// Browse specific folder path
const { media: folderMedia } = await coreviz.media.browse('col_123', {
  path: 'col_123.folder_abc',
  limit: 100,
});

// Filter by media type
const { media: images } = await coreviz.media.browse('col_123', {
  type: 'image',
  sortBy: 'createdAt',
  sortDirection: 'desc',
});

// Filter by date range
const { media: recentMedia } = await coreviz.media.browse('col_123', {
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31',
});

// Filter by tags
const { media: taggedMedia } = await coreviz.media.browse('col_123', {
  tagFilters: { color: ['red', 'blue'], category: ['product'] },
});

// Semantic search within collection
const { media: searchResults } = await coreviz.media.browse('col_123', {
  q: 'red sneakers on white background',
});

// Find similar by object ID
const { media: similar } = await coreviz.media.browse('col_123', {
  similarToObjectId: 'obj_detected_123',
  similarToObjectModel: 'objects',
});

// Recursive listing (all descendants)
const { media: allMedia } = await coreviz.media.browse('col_123', {
  recursive: true,
});
```

### Response
#### Success Response (200)
- **media** (array) - A list of media item objects.
  - **id** (string) - The unique identifier for the media item.
  - **name** (string) - The name of the media item.
  - **type** (string) - The type of the media item (e.g., 'image', 'video').
  - **createdAt** (string) - The creation timestamp.
  - **tags** (object) - Tags associated with the media item.
  - **blobUrl** (string) - URL to the media file.
- **pagination** (object) - Pagination information.
  - **total** (integer) - The total number of items available.
  - **limit** (integer) - The limit used for the current request.
  - **offset** (integer) - The offset used for the current request.

#### Response Example
```json
{
  "media": [
    {
      "id": "obj_123",
      "name": "image.jpg",
      "type": "image",
      "createdAt": "2024-05-15T10:00:00Z",
      "tags": { "color": ["red"], "category": ["product"] },
      "blobUrl": "https://cdn.coreviz.com/org_abc/col_123/obj_123.jpg"
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 50,
    "offset": 0
  }
}
```
```

--------------------------------

### Create New Collection

Source: https://github.com/coreviz/sdk/blob/main/README.md

Creates a new collection with a given name and an optional icon. The collection can be targeted to a specific organization or the user's default organization.

```typescript
// Create in current user's org
const collection = await coreviz.collections.create('Product Photos', '📦');

// Create in a specific org
const collection = await coreviz.collections.create('Product Photos', '📦', 'org_abc123');
```