# VIUCraft — Full LLM Reference

> API-first image processing platform: upload an image once, then transform it on the fly
> via URL. ~35 operations, an official zero-dependency JavaScript/TypeScript SDK, an MCP
> server for agents, and a fully machine-readable contract (OpenAPI 3.1).
>
> This single file contains everything needed to integrate VIUCraft from a cold start —
> the quickstart, the upload response, the URL grammar, the tenancy model, auth, errors,
> and discovery — with no test upload or registry spelunking required.

Last updated: 2026-06-16

---

## 1. Tenancy model (read this first)

Every request — upload **and** delivery — uses **your tenant subdomain**:
`https://<your-subdomain>.viucraft.com`.

Free-tier accounts share a host instead: `https://viucraft.com/free/acc_<customer_id>/...`.

You can discover your own subdomain, plan, and capabilities from just an API key — see §8 Discovery.

## 2. Authentication

- REST endpoints (`/api/*`, upload, delivery): header `X-API-Key: vc_live_...` (live) or `vc_test_...` (test).
- MCP endpoint (`POST /mcp`): header `Authorization: Bearer vc_live_...`.
- HTTPS only. Never put the key in a URL.

## 3. Quickstart — official SDK (recommended)

```bash
npm install viucraft
```

```ts
import { ViucraftClient } from "viucraft";

const client = new ViucraftClient({ apiKey, subdomain });   // built-in auth, timeout, 429-retry

// Upload (Blob | File; { folder? } optional)
const { image_id } = await client.images.upload(blob);      // image_id is your stored handle

// Build a transform URL (pure, no network)
const url = client.image(image_id)
  .resize(800, 600)
  .setFormat("webp")                                        // handles the mandatory extension for you
  .toURL();                                                 // -> https://<sub>.viucraft.com/resize_width_800_height_600/<id>.webp

await client.images.delete(image_id);                       // 204
```

The SDK is zero-dependency, typed, dual ESM+CJS, Node ≥18, MIT. Source: https://github.com/BStorm-IT/viucraft-js

## 4. Quickstart — raw HTTP (curl)

```bash
# Upload
curl -X POST "https://<your-subdomain>.viucraft.com/upload" \
  -H "X-API-Key: vc_live_..." \
  -F "image=@photo.png"
# -> 201 Created (see §5 for the full response body)

# Deliver original (extension is MANDATORY)
curl "https://<your-subdomain>.viucraft.com/<image_id>.png"

# Deliver a transform
curl "https://<your-subdomain>.viucraft.com/resize-800-600/<image_id>.webp"

# Delete
curl -X DELETE "https://<your-subdomain>.viucraft.com/api/images/<image_id>" \
  -H "X-API-Key: vc_live_..."
# -> 204 No Content
```

## 5. Upload — `POST /upload`

Body: `multipart/form-data`, field name = `image`. Optional `folder` field.

Success → `201 Created`:

```json
{
  "image_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://<subdomain>.viucraft.com/<image_id>.png",
  "filename": "original-name.png",
  "folder": "/",
  "metadata": {
    "width": 1200, "height": 800, "format": "png",
    "file_size": 528421, "color_space": "srgb", "has_alpha": false
  },
  "created_at": "2026-06-16T09:44:35+00:00",
  "storage": { "used": 235748582, "limit": 21474836480, "used_percent": 1.1 }
}
```

If the identical image already exists you get `200 OK` with `"duplicate": true` and the existing `image_id`.

**The one thing that must be clear:** `image_id` is the **permanent, canonical handle — store this**.
`filename` is only the original upload name (not stable, collision-prone) — **never key on it**.

## 6. Delivery / transform URL grammar

Shape (paid tier):

```
https://<subdomain>.viucraft.com/<operations>/<image_id>.<ext>
```

Free tier:

```
https://viucraft.com/free/acc_<customer_id>/<operations>/<image_id>.<ext>
```

Rules:
- The **file extension is mandatory.** `image_id` has no extension — combine it with `metadata.format`
  (or any supported output format). A bare `/<image_id>` (no extension) is not a valid delivery path.
- Omit the `<operations>` segment entirely for the canonical (untransformed) image:
  `https://<subdomain>.viucraft.com/<image_id>.<ext>`. Do not emit an empty segment (`//`).
- Output formats: `jpg`, `jpeg`, `png`, `webp`, `avif`, `gif`, `tiff`.

Operation grammar — two interchangeable forms:
- **Long (underscore):** `resize_width_800_height_600`
- **Short (dash):** `resize-800-600`

Chain operations by separating with `/`:

```
/resize-1200-800/sharp-1.2/q-85/<image_id>.webp
/grayscale/<image_id>.png
/thumbnail_width_300_height_200_crop_entropy/<image_id>.jpg
```

~35 operations exist (resize, crop, thumbnail, smartcrop, rotate, flip, grayscale, blur, sharpen,
quality, tint, colorize, vignette, watermark, …). Full list with parameters: `/llms/operations.txt`
and the OpenAPI spec (§9).

## 7. Endpoint map (base-path split)

| Purpose | Method + path | Host |
|---|---|---|
| Upload | `POST /upload` (also `POST /api/upload`) | your subdomain |
| Bulk upload | `POST /api/upload/bulk` | your subdomain / api |
| Deliver / transform | `GET /<ops>/<image_id>.<ext>` | your subdomain |
| List images | `GET /api/images` | api |
| Image metadata | `GET /api/images/<image_id>` | api |
| Delete image | `DELETE /api/images/<image_id>` → `204` | api |
| Batch jobs | `POST /api/v1/jobs`, `GET /api/v1/jobs/<id>` (+ SSE) | api |
| Webhooks | `POST /api/webhooks`, `GET/DELETE /api/webhooks/<id>` | api |
| Discovery | `GET /api/v1/cli/whoami` | api |
| OpenAPI spec | `GET /api/openapi.json`, `GET /api/openapi.yaml` | api |
| MCP (agents) | `POST /mcp` (Bearer auth) | api |

Rule of thumb: **upload + delivery at the root; management/CRUD under `/api/`.**

## 8. Discovery — bootstrap from just an API key

```
GET /api/v1/cli/whoami        (X-API-Key)
```

Returns your `customer` (`email`, `name`, `plan`, `subdomain`) and `usage` (images, storage,
transformations). Use it to learn your own subdomain and capabilities without asking a human.
(Capabilities are also available via `GET /api/capabilities`.)

## 9. Machine-readable contract

- **OpenAPI 3.1:** `GET /api/openapi.json` (or `.yaml`) — covers upload, delivery/transform, list,
  delete, batch, and webhooks with request + response schemas and code samples. Public, cacheable.
- **Agent skills:** `/.well-known/skills/` (SKILL.md + references).
- **MCP server:** `POST /mcp` exposes upload / transform / delete / discovery tools for agents.
- **This file + index:** `/llms.txt` (index) and `/llms-full.txt` (this file); topic files under `/llms/`.

## 10. Errors

Errors return a structured JSON envelope:

```json
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Human-readable explanation",
    "status": 400,
    "docs_url": "https://viucraft.com/docs/...",
    "retryable": false,
    "request_id": "req_...",
    "suggested_fix": "What to change",
    "violations": []
  }
}
```

Status codes: `201` upload created · `200` delivery / duplicate upload · `204` delete · `400`
invalid parameter/operation · `401` bad/missing key · `403` suspended/banned · `404` not found ·
`415` unsupported format · `429` rate / usage limit (honor `Retry-After`) · `5xx` server.

On `429`, retry after the `Retry-After` header. The official SDK does this automatically.

## 11. Links

- Docs: https://viucraft.com/docs
- OpenAPI: https://viucraft.com/api/openapi.json
- Postman collection (generated from the spec): https://viucraft.com/api/postman.json
- Quickstart + agent recipe: https://viucraft.com/docs/article/quickstart
- SDK (npm): https://www.npmjs.com/package/viucraft — `npm install viucraft`
- SDK source: https://github.com/BStorm-IT/viucraft-js
- Topic references: /llms/operations.txt, /llms/sdk.txt, /llms/api.txt, /llms/mcp.txt, /llms/errors.txt, /llms/pricing.txt