Quickstart

Get your first image hosted in 30 seconds. No signup form, no dashboard — just API calls.

1. Register an account

npx pixelvault-cli register

Response:

JSON

{
  "account": {
    "id": "acct_abc123",
    "email": "you@example.com"
  },
  "project": {
    "id": "proj_xyz789",
    "name": "Default"
  },
  "apiKey": "pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Save your API key — it's shown only once.

2. Upload an image

npx pixelvault-cli upload screenshot.png

Response:

JSON

{
  "id": "img_abc123",
  "url": "https://img.pixelvault.dev/proj_xyz789/img_abc123.png",
  "mime_type": "image/png",
  "size_bytes": 245000,
  "width": 1200,
  "height": 800
}

3. Use the URL

The CDN URL is live immediately. Use it in markdown, HTML, or anywhere you need an image.

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

Authentication

All API requests (except registration) require a Bearer token:

Authorization: Bearer pv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys use the prefix pv_live_ for production and pv_test_ for test environments. Keys are hashed server-side — we never store the raw key.

API Reference

Base URL: https://api.pixelvault.dev

All responses are JSON. Errors follow the format:

Error response

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

POST /v1/auth/register

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

Field	Type	Required
email	string	Yes
password	string (8+ chars)	Yes

POST /v1/images

Upload an image. Accepts multipart/form-data.

Field	Type	Required
file	binary	Yes
folder	string	No

Supported formats: JPEG, PNG, GIF, WebP, AVIF, SVG.

GET /v1/images

List images in your project. Paginated.

Param	Type	Default
limit	integer	50
offset	integer	0

GET /v1/images/:id

Get a single image's metadata by ID.

DELETE /v1/images/:id

Delete an image. Removes from storage and CDN.

CLI

The pixelvault-cli package gives you one-liner uploads from any terminal. Designed for AI coding agents — URLs go to stdout, messages to stderr.

npm install -g pixelvault-cli

Or use directly with npx:

npx pixelvault-cli register          # Create account, stores API key
npx pixelvault-cli upload photo.jpg  # Prints CDN URL to stdout
npx pixelvault-cli list              # One URL per line
npx pixelvault-cli delete img_abc    # Silent on success

For CI/CD and headless agent usage, set PIXELVAULT_API_KEY:

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

Source: github.com/pixelvault-dev/cli

Claude Code skill

PixelVault ships a Claude Code skill so your agent can upload images without leaving the conversation.

claude plugin add pixelvault-dev/skill

Once installed, three skills are available:

Skill	Description
`/pixelvault-upload <file>`	Upload image(s), get CDN URLs
`/pixelvault-setup`	Install CLI and configure API key
`/pixelvault-list`	List recent uploads

The upload skill can also be triggered automatically — when Claude sees "upload this screenshot" or needs to host an image, it invokes the skill without you typing the command.

The skill wraps the pixelvault-cli, so make sure it's installed first (or run /pixelvault-setup).

Source: github.com/pixelvault-dev/skill

Agent discovery

PixelVault provides standard discovery endpoints for any AI agent:

/.well-known/api-catalog — API catalog for agent discovery
/llms.txt — LLM-readable service description
/openapi.json — OpenAPI 3.1 specification