PixelVault

https://pixelvault.dev/docs
Admin
PixelVault is an agent-first image hosting API that enables developers and AI agents to upload...
Tokens:7,581
Snippets:100
Trust Score:6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install PixelVault CLI

Source: https://pixelvault.dev/docs

Global installation of the CLI package via npm.

```bash
npm install -g pixelvault-cli
```

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

### Install and initialize PixelVault paste package

Source: https://pixelvault.dev/docs

Installation and usage of the framework-agnostic npm package for bundled applications.

```bash
npm install @pixelvault-dev/paste
```

```javascript
import { attachPaste, openFilePicker } from "@pixelvault-dev/paste";

const field = document.querySelector("textarea");
const options = { publishableKey: "pv_pub_xxxxxxxx" };

attachPaste(field, options);                       // paste + drop
uploadButton.addEventListener("click", () => openFilePicker(field, options));
```

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

### GET /v1/images

Source: https://pixelvault.dev/docs.md

List images in your project.

```APIDOC
## GET /v1/images

### Description
List images in your project. Paginated.

### Method
GET

### Endpoint
/v1/images

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Default 50
- **offset** (integer) - Optional - Default 0
```

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

### Install Claude Code skill

Source: https://pixelvault.dev/docs

Command to add the PixelVault skill to your Claude Code environment.

```bash
claude plugin add pixelvault-dev/skill
```

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

### GET /v1/images

Source: https://pixelvault.dev/docs

List images in your project with pagination.

```APIDOC
## GET /v1/images

### Description
List images in your project. Paginated.

### Method
GET

### Endpoint
/v1/images

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Number of items to return (default 50)
- **offset** (integer) - Optional - Number of items to skip (default 0)
```

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

### Use the CDN URL in Markdown

Source: https://pixelvault.dev/docs

Example of embedding the hosted image URL in a Markdown document.

```markdown
![Screenshot](https://img.pixelvault.dev/proj_xyz789/img_abc123.png)
```

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

### GET /v1/export-jobs/:id/download

Source: https://pixelvault.dev/docs

Streams the completed export archive.

```APIDOC
## GET /v1/export-jobs/:id/download

### Description
Streams the .tar archive once the export job status is complete.

### Method
GET

### Endpoint
/v1/export-jobs/:id/download

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the export job.
```

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

### GET /v1/images/:id

Source: https://pixelvault.dev/docs

Get a single image's metadata by ID.

```APIDOC
## GET /v1/images/:id

### Description
Get a single image's metadata by ID.

### Method
GET

### Endpoint
/v1/images/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the image
```

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

### GET /v1/export-jobs/:id

Source: https://pixelvault.dev/docs

Retrieves the current status of an export job.

```APIDOC
## GET /v1/export-jobs/:id

### Description
Polls the status of an export job. Once the status is 'complete', a download_url is included in the response.

### Method
GET

### Endpoint
/v1/export-jobs/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the export job.

### Response
#### Success Response (200)
- **status** (string) - The current status of the job (e.g., processing, complete).
- **processed_count** (integer) - Number of images processed so far.
- **image_count** (integer) - Total number of images in the project.
- **download_url** (string) - Optional - The URL to download the archive once complete.
```

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

### POST /v1/auth/register

Source: https://pixelvault.dev/docs

Create a new account. Returns an account, a default project, and an API key.

```APIDOC
## POST /v1/auth/register

### Description
Create a new account. Returns an account, a default project, and an API key. The password is optional.

### Method
POST

### Endpoint
/v1/auth/register

### Parameters
#### Request Body
- **email** (string) - Required - User email address
- **password** (string) - Optional - Password (8+ chars)
```

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

### Register a PixelVault account

Source: https://pixelvault.dev/docs

Create a new account using the CLI or a POST request to the authentication endpoint.

```bash
npx pixelvault-cli register
```

```bash
curl -X POST https://api.pixelvault.dev/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
```

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

### Upload Options and Configuration

Source: https://pixelvault.dev/docs

Advanced upload flags for bulk processing, JSON output, and private signed URL generation.

```bash
npx pixelvault-cli upload *.png --folder icons          # Bulk upload (shell glob), grouped in a folder
npx pixelvault-cli upload shot.png --json               # Full JSON response instead of the bare URL
npx pixelvault-cli upload secret.png --private          # Private signed URL (needs a secret key)
npx pixelvault-cli upload secret.png --private --expires 24h  # …with a 24h link lifetime (default 7d)
```

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

### Configure API Key for CI/CD

Source: https://pixelvault.dev/docs

Setting the PIXELVAULT_API_KEY environment variable for headless authentication.

```bash
export PIXELVAULT_API_KEY=pv_live_xxx
npx pixelvault-cli upload screenshot.png
```

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

### POST /v1/export

Source: https://pixelvault.dev/docs

Initiates a background job to export all images in a project as a .tar archive.

```APIDOC
## POST /v1/export

### Description
Initiates a background job to export all images in a project as a .tar archive. The process follows a start, poll, and download flow.

### Method
POST

### Endpoint
/v1/export

### Response
#### Success Response (202)
- **job_id** (string) - The unique identifier for the export job.
- **status** (string) - The current status of the job (e.g., pending).
- **image_count** (integer) - Total number of images to be exported.
- **status_url** (string) - The URL to poll for job status updates.
```

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

### PixelVault CLI Commands

Source: https://pixelvault.dev/docs

Common CLI operations for account management, image manipulation, and data retrieval.

```bash
npx pixelvault-cli register          # Create account, stores API key
npx pixelvault-cli register --email you@example.com --passwordless  # Headless/agent signup
npx pixelvault-cli upload photo.jpg  # Prints CDN URL to stdout
npx pixelvault-cli list              # One URL per line
npx pixelvault-cli get img_abc       # Print URL, or download with -o (and -t to transform)
npx pixelvault-cli delete img_abc    # Silent on success
npx pixelvault-cli export            # Download all your images as a .tar (manifest + every image)
```

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

### Apply CDN image transformations

Source: https://pixelvault.dev/docs

Resize, crop, and convert images on-the-fly by appending query parameters to the CDN URL.

```url
https://img.pixelvault.dev/proj_xyz789/img_abc123.jpg?w=400&fit=cover&fmt=webp
```

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

### POST /v1/images/:id/sign-url

Source: https://pixelvault.dev/docs

Mint a fresh signed URL for an existing image.

```APIDOC
## POST /v1/images/:id/sign-url

### Description
Mint a fresh signed URL for an existing image.

### Method
POST

### Endpoint
/v1/images/:id/sign-url

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the image
#### Request Body
- **expires_in** (integer) - Optional - Signature lifetime in seconds (default 3600)
```

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

### POST /v1/auth/register

Source: https://pixelvault.dev/docs.md

Registers a new account with the PixelVault service.

```APIDOC
## POST /v1/auth/register

### Description
Registers a new account to obtain an API key for image hosting.

### Method
POST

### Endpoint
https://api.pixelvault.dev/v1/auth/register

### Request Body
- **email** (string) - Required - The email address for the account.

### Response
#### Success Response (200)
- **data** (object) - Contains account details including account_id, email, and default_project information.
```

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

### Implement browser paste-and-host via script tag

Source: https://pixelvault.dev/docs

Drop-in script tag implementation for enabling image uploads in textareas without a build step.

```html
<textarea data-pixelvault></textarea>
<button data-pv-pick="[data-pixelvault]">Upload image</button>
<script src="https://pixelvault.dev/paste.js"
        data-pv-key="pv_pub_xxxxxxxx"
        data-pv-target="[data-pixelvault]"></script>
```

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

### Upload an image

Source: https://pixelvault.dev/docs

Upload a local file to the CDN using the CLI or a multipart/form-data POST request.

```bash
npx pixelvault-cli upload screenshot.png
```

```bash
curl -X POST https://api.pixelvault.dev/v1/images \
  -H "Authorization: Bearer pv_live_xxxxxxxx" \
  -F "file=@screenshot.png"
```

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

### POST /v1/images

Source: https://pixelvault.dev/docs

Uploads an image file to the PixelVault CDN.

```APIDOC
## POST /v1/images

### Description
Uploads an image file and returns a CDN URL.

### Method
POST

### Endpoint
https://api.pixelvault.dev/v1/images

### Parameters
#### Request Body
- **file** (file) - Required - The image file to upload.

### Response
#### Success Response (200)
- **data** (object) - Contains image metadata including id, url, visibility, mime_type, size, filename, and created_at.
```

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

### MCP Tools

Source: https://pixelvault.dev/docs

List of tools exposed by the PixelVault MCP server for image management.

```APIDOC
## Available Tools

- **upload_image**: Upload an image (base64 data or public source_url) to receive a CDN URL. Supports optional `expires_in`.
- **upload_batch**: Upload 1–50 images in a single call. Supports `visibility: "private"` for signed URLs.
- **sign_url**: Generate a time-limited signed URL for a private image by ID.
- **transform_image**: Generate an on-the-fly transformation URL (resize, crop, format, background removal, effects, watermark).
- **list_images**: Retrieve a paginated list of your images.
- **get_image**: Retrieve metadata and the CDN URL for a specific image.
- **delete_image**: Remove an image from the system.
- **rescue_imgur**: Scan a page for hotlinked Imgur images and generate rescue URLs (no API key required).
```

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

### MCP Server Configuration

Source: https://pixelvault.dev/docs

Configuration details for connecting to the PixelVault MCP server using an API key or OAuth.

```APIDOC
## MCP Server Connection

### Endpoint
https://mcp.pixelvault.dev/mcp

### Transport
streamable-http

### Authentication
- **Bearer Token**: Pass your API key in the Authorization header.
- **OAuth**: Use https://mcp.pixelvault.dev/mcp/oauth for consent-based authentication.
```

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

### Account registration response

Source: https://pixelvault.dev/docs

The JSON structure returned upon successful account registration.

```json
{
  "data": {
    "account_id": "acct_abc123",
    "email": "you@example.com",
    "email_verified": false,
    "password_set": false,
    "plan": "free",
    "default_project": {
      "id": "proj_xyz789",
      "name": "Default",
      "api_keys": { "live": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}
```

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

### Export project images via API

Source: https://pixelvault.dev/docs

Initiate an export job, poll the status, and download the resulting tar archive once processing is complete.

```http
POST /v1/export
→ 202 { "job_id": "exp_…", "status": "pending", "image_count": 327,
        "status_url": "/v1/export-jobs/exp_…" }

GET /v1/export-jobs/:id
→ { "status": "processing", "processed_count": 120, "image_count": 327 }
   # when status is "complete", the response adds "download_url"

GET /v1/export-jobs/:id/download   # streams application/x-tar once complete
```

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

### Configure MCP Client via JSON

Source: https://pixelvault.dev/docs

Configuration structure for clients supporting the streamableHttp transport.

```json
{
  "mcpServers": {
    "pixelvault": {
      "type": "streamable-http",
      "url": "https://mcp.pixelvault.dev/mcp",
      "headers": { "Authorization": "Bearer pv_live_xxxxxxxx" }
    }
  }
}
```

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

### POST /v1/auth/register

Source: https://pixelvault.dev/docs

Registers a new account to obtain an API key for image uploads.

```APIDOC
## POST /v1/auth/register

### Description
Registers a new account. Password is optional; omit it for a passwordless agent account.

### Method
POST

### Endpoint
https://api.pixelvault.dev/v1/auth/register

### Request Body
- **email** (string) - Required - The email address for the account.

### Response
#### Success Response (200)
- **data** (object) - Contains account details including account_id, email, and default_project information with API keys.
```

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

### Apply visual effects

Source: https://pixelvault.dev/docs

Stack and combine various effects like blur, saturation, rotation, and flipping with resizing.

```text
.../img_abc123.jpg?blur=30                       # blurred
.../img_abc123.jpg?saturation=0                  # grayscale
.../img_abc123.jpg?rotate=90&flip=h              # rotated + mirrored
.../img_abc123.jpg?w=800&blur=30&saturation=0    # grayscale, blurred 800px thumbnail
```

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

### ChatGPT Custom GPT Action OpenAPI URL

Source: https://pixelvault.dev/docs

Use this URL in the ChatGPT GPT editor under Actions to import the PixelVault API specification.

```text
https://pixelvault.dev/openapi-actions.json
```

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

### Apply watermark tiles

Source: https://pixelvault.dev/docs

Reference an uploaded image filename to tile it over the base image.

```text
.../img_abc123.jpg?tile=img_logo.png             # your logo, tiled at native size
.../img_abc123.jpg?w=1200&tile=watermarks/brand.png   # resized + watermarked
```

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

### Add PixelVault MCP to Claude Code

Source: https://pixelvault.dev/docs

Command to register the PixelVault MCP server in Claude Code using an API key as a Bearer token.

```bash
claude mcp add --transport http pixelvault https://mcp.pixelvault.dev/mcp \
  --header "Authorization: Bearer pv_live_xxxxxxxx"
```

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

### POST /v1/images/batch

Source: https://pixelvault.dev/docs

Upload multiple images in one request, grouped into a collection.

```APIDOC
## POST /v1/images/batch

### Description
Upload many images in one request, grouped into a collection. Keyed only.

### Method
POST

### Endpoint
/v1/images/batch
```

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

### PixelVault MCP Server URL

Source: https://pixelvault.dev/docs

The endpoint for the remote Model Context Protocol server using streamable-http transport.

```text
https://mcp.pixelvault.dev/mcp   (transport: streamable-http)
```

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

### Batch Upload Images

Source: https://pixelvault.dev/docs

Upload multiple images in a single request, grouped by a collection. This endpoint requires an API key and is idempotent.

```http
POST /v1/images/batch
{
  "collection": { "type": "ci_build", "name": "run-123", "visibility": "private" },
  "images": [ { "data": "<base64>", "filename": "diff.png" } ]
}
```

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

### Image Transformation Parameters

Source: https://pixelvault.dev/docs

The API supports various query parameters to transform images. Parameters can be combined to achieve complex effects.

```APIDOC
## Image Transformation Parameters

### Query Parameters
- **size** (string) - Optional - Named preset (s, m, l, social).
- **w, h** (integer) - Optional - Width/height in pixels.
- **fit** (string) - Optional - Resizing strategy (scale-down, contain, cover, crop, pad).
- **fmt** (string) - Optional - Output format (webp, avif, jpg, png, auto).
- **q** (integer/string) - Optional - Output quality (auto, 60, 75, 85).
- **segment** (string) - Optional - Background removal (foreground).
- **background** (string) - Optional - Background color (hex, rgb/rgba, named color).
- **gravity** (string) - Optional - Crop focus (auto, face, left, right, top, bottom, XxY).
- **zoom** (float) - Optional - Face-crop tightness (0.0–1.0).
- **blur** (integer) - Optional - Gaussian blur (0–250).
- **sharpen** (integer) - Optional - Sharpen strength (0–10).
- **rotate** (integer) - Optional - Rotation in 90-degree steps (90, 180, 270).
- **flip** (string) - Optional - Mirroring (h, v, hv).
- **brightness** (float) - Optional - Brightness multiplier (0.5, 0.75, 1.25, 1.5, 2).
- **contrast** (float) - Optional - Contrast multiplier (0.5, 0.75, 1.25, 1.5, 2).
- **saturation** (float) - Optional - Saturation multiplier (0, 0.5, 1.5, 2).
- **tile** (string) - Optional - Filename of a watermark image.
```

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

### AI Agent Discovery Endpoints

Source: https://pixelvault.dev/docs

Standard endpoints provided by PixelVault for AI agent discovery and service description.

```text
/.well-known/api-catalog — API catalog for agent discovery
/llms.txt — LLM-readable service description (lists the MCP server)
/openapi.json — OpenAPI 3.1 specification
/openapi-actions.json — trimmed spec for ChatGPT Custom GPT Actions
MCP server — https://mcp.pixelvault.dev/mcp (API key) or /mcp/oauth (OAuth)
```

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

### Render Image in React Email

Source: https://pixelvault.dev/docs

Use this component to display hosted images in react-email templates, utilizing URL parameters for on-the-fly resizing.

```jsx
<Img src={`${logoUrl}?w=240&fmt=auto`} width="120" />
```

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

### POST /v1/images

Source: https://pixelvault.dev/docs

Upload an image. Supports multipart/form-data for files or application/json for URLs.

```APIDOC
## POST /v1/images

### Description
Upload an image. Accepts multipart/form-data (a file) or, with an API key, application/json (a URL).

### Method
POST

### Endpoint
/v1/images

### Parameters
#### Request Body
- **file** (binary) - Required* - Image file
- **folder** (string) - Optional - Folder path
- **expires_in** (integer) - Optional - Expiration time in seconds
```

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

### Apply background removal

Source: https://pixelvault.dev/docs

Isolates the subject and makes the background transparent or fills it with a specified color.

```text
.../img_abc123.jpg?segment=foreground                    # transparent PNG cut-out
.../img_abc123.jpg?segment=foreground&background=white   # subject on a white fill
.../img_abc123.jpg?w=400&h=400&fit=cover&gravity=face&segment=foreground   # portrait cut-out
```

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

### Authenticate API Requests

Source: https://pixelvault.dev/docs

Include this header in all API requests except registration to authenticate.

```http
Authorization: Bearer pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

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

### Image upload response

Source: https://pixelvault.dev/docs

The JSON structure returned after a successful image upload, containing the CDN URL.

```json
{
  "data": {
    "id": "img_abc123",
    "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
    "visibility": "public",
    "mime_type": "image/png",
    "size": 245000,
    "filename": "screenshot.png",
    "folder": null,
    "created_at": "2026-07-15T12:00:00.000Z"
  }
}
```

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

### API Error Response Format

Source: https://pixelvault.dev/docs

Standard JSON structure returned when an API request fails.

```json
{
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}
```

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

### DELETE /v1/images/:id

Source: https://pixelvault.dev/docs.md

Delete an image.

```APIDOC
## DELETE /v1/images/:id

### Description
Delete an image. Removes from storage and CDN.

### Method
DELETE

### Endpoint
/v1/images/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Image ID
```

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

### DELETE /v1/images/:id

Source: https://pixelvault.dev/docs

Delete an image from storage and CDN.

```APIDOC
## DELETE /v1/images/:id

### Description
Delete an image. Removes from storage and CDN.

### Method
DELETE

### Endpoint
/v1/images/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the image
```
Tokens:
Raw