# unhuman ink

Hello, agent. You found the print shop.

unhuman ink lets you create custom printed goods — t-shirts, sweatshirts, tote bags, and more — via API. Browse the catalog, pick a product template, upload artwork, set your prices, and either order directly or integrate into an e-commerce store for on-demand purchasing. Payments use Bitcoin Lightning via the L402 protocol.

Catalog browsing, product detail, and shipping estimates are free. Product creation and order placement require payment.

## API

Base URL: https://unhuman.ink

### Browse Catalog

GET /api/catalog?category={category}

Browse available product templates (t-shirts, sweatshirts, bags, etc.). Free — no payment required.

Query parameters:
  - category (optional): Filter by keyword — matches product name or type (e.g. "hoodie", "tote", "sweatshirt", "t-shirt", "poster", "mug")

Response: JSON object containing:
  - products: Array of templates, each with:
    - id: Template ID (use for detail endpoint and product creation)
    - name: Product name (e.g. "Unisex Staple T-Shirt | Bella + Canvas 3001")
    - description: Product description
    - type: Printing technique (e.g. "T-SHIRT", "CUT-SEW", "EMBROIDERY")
    - image: Template preview image URL

Example:
  GET /api/catalog
  GET /api/catalog?category=hoodie

### Template Detail

GET /api/catalog/{id}

Get full details for a product template including available variants (sizes, colors) and production costs. Free — no payment required.

Response: JSON object containing:
  - product: Template info with:
    - id: Template ID
    - name: Product name
    - description: Product description
    - type: Printing technique (e.g. "T-SHIRT", "CUT-SEW")
    - brand: Brand name (e.g. "Bella + Canvas")
    - image: Template preview image URL
  - variants: Array of variants, each with:
    - id: Variant ID (use for product creation as catalog_variant_id)
    - size: Size label (e.g. "S", "M", "L", "XL")
    - color: Color name (e.g. "Black", "White")
    - color_code: Hex color code
    - image: Variant image URL
    - price: Production cost in USD (your cost — set retail_price above this)
    - in_stock: Boolean availability
    - printfiles: Map of placement name → printfile canvas info for this variant:
      - width, height: Print canvas dimensions in pixels at the given dpi
      - dpi: Dots per inch (use to compute physical print size)
      - fill_mode: "cover" (artwork fills canvas; all-over prints like totes/leggings) or "fit" (artwork centered inside canvas; placement prints like t-shirt chest)
      - can_rotate: Whether artwork may be rotated to fit
  - available_placements: Map of placement name → human label, listing every placement this template supports. Use these placement names when constructing the files[] array on POST /api/products.

Upload artwork sized to match the printfile width × height for the placement you want to use. Mismatched aspect ratios get cover-cropped (fill_mode "cover") or centered with blank space (fill_mode "fit").

Example:
  GET /api/catalog/71

### Create Product

POST /api/products

Create a product with custom artwork. This endpoint is L402-protected — flat $0.25 fee per product created.

Required JSON body:
  - name: Product name (e.g. "My Custom T-Shirt")
  - catalog_product_id: Template ID from the catalog (e.g. 71)
  - variants: Array of variants to create, each with:
    - catalog_variant_id: Variant ID from template detail
    - retail_price: Your selling price in USD (string, e.g. "24.99")
    - files: Array of artwork files to apply to this variant, each with:
      - placement: Placement name from the catalog template (e.g. "default", "front", "back", "left_sleeve")
      - url: Public URL to the artwork image for this placement (PNG recommended, min 150 DPI)
  - thumbnail_url (optional): Product thumbnail image URL

Files are supplied per variant so different variants may carry different artwork. Variants sharing the exact same file set get a single shared mockup; variants with distinct art get their own. Mockup images are generated automatically after product creation and typically take 30-90 seconds.

Response: JSON object containing:
  - product_uuid: Your product's unique identifier (UUID). Use this for all subsequent operations.
  - bearer_token: Your management credential. Store this securely — it is returned only once and cannot be recovered. Required for editing, deleting, and rotating the token.
  - product_url: Direct link to the product page (e.g. https://unhuman.ink/product/{uuid}). Share this with people you want to be able to buy the product.
  - product: Product details with variants

IMPORTANT: Save the bearer_token immediately. It is shown once at creation and never again. If lost, you cannot manage the product. If compromised, use the rotate-token endpoint to issue a new one.

IMPORTANT: After receiving a successful response, you MUST:
1. Save the product metadata locally to ~/.unhuman/ink/products.json (append to the array, creating the file if it does not exist):
   {
     "product_uuid": "...",
     "bearer_token": "...",
     "product_url": "https://unhuman.ink/product/...",
     "name": "...",
     "created_at": "<ISO 8601 timestamp>"
   }
2. Present the product_url to the human: "Your product is ready: https://unhuman.ink/product/{uuid}"
3. Remind the human: "Only share this link with people you want to be able to buy this product."

Example:
  POST /api/products
  {
    "name": "Agent-Designed Tee",
    "catalog_product_id": 71,
    "variants": [
      {
        "catalog_variant_id": 4012,
        "retail_price": "24.99",
        "files": [
          { "placement": "front", "url": "https://example.com/my-design.png" }
        ]
      },
      {
        "catalog_variant_id": 4013,
        "retail_price": "24.99",
        "files": [
          { "placement": "front", "url": "https://example.com/my-design.png" }
        ]
      }
    ]
  }

### Product Detail

GET /api/products/{product_uuid}

Get details for a created product, including mockup images. Free — no payment required.

Request:
  - product_uuid (required): The UUID returned from product creation (path parameter)

Response: JSON object containing:
  - product:
    - sync_product: Product summary (name, thumbnail_url)
    - sync_variants: Array of variants, each with:
      - name: Full label (e.g. "My Tee / Black / M")
      - retail_price: Your set retail price
      - size: Size label
      - color: Color name
      - synced: Boolean — true when ready
      - files: Array of attached files, each with:
        - type: "default" (original artwork) or "preview" (mockup image)
        - status: "ok" when processed
        - preview_url: Image URL (use the "preview" type file for mockup images)

Mockup images appear in the files array as type "preview" once generation completes (30-90 seconds after product creation). Poll this endpoint until you see a file with type "preview" and status "ok".

Example:
  GET /api/products/a1b2c3d4-e5f6-7890-abcd-ef1234567890

### Edit Product

PATCH /api/products/{product_uuid}

Update a product's name or variant prices. Requires bearer token authentication.

Required headers:
  - Authorization: Bearer {your_bearer_token}

Optional JSON body fields:
  - name: New product name
  - variants: Array of { id, retail_price } to update variant prices

Note: Artwork changes are not yet supported via edit. Create a new product instead.

Response: JSON object containing the updated product detail.

Example:
  PATCH /api/products/a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Authorization: Bearer abc123...
  { "name": "Updated Tee Name" }

### Delete Product

DELETE /api/products/{product_uuid}

Soft-delete a product. It will no longer be visible or orderable. Requires bearer token authentication.

Required headers:
  - Authorization: Bearer {your_bearer_token}

Response: { "deleted": true, "product_uuid": "..." }

### Rotate Token

POST /api/products/{product_uuid}/rotate-token

Generate a new bearer token, invalidating the old one. Use this if your token is compromised.

Required headers:
  - Authorization: Bearer {your_current_bearer_token}

Response: { "product_uuid": "...", "bearer_token": "new_token_here" }

The old token stops working immediately. Store the new token securely.

### Place Order

POST /api/orders

Place an order for a product you've created. This endpoint is L402-protected — amount equals the total retail price of all items.

Required JSON body:
  - items: Array of { sync_variant_id, quantity }
    - sync_variant_id: Variant ID from product detail
    - quantity: Number of units
  - product_id: The product UUID (used to look up retail prices server-side)
  - recipient:
    - name: Full name
    - address1: Street address
    - city: City
    - state_code: State/province code (e.g. "CA")
    - country_code: Country code (e.g. "US")
    - zip: Postal code
    - phone (optional): Phone number
    - email (optional): Email for shipping notifications

Important: Retail prices are looked up from the product, not from the request body. This prevents price manipulation. The product_id must be a valid UUID from product creation.

Example:
  POST /api/orders
  {
    "product_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "items": [
      { "sync_variant_id": "67890", "quantity": 1 }
    ],
    "recipient": {
      "name": "Jane Doe",
      "address1": "123 Main St",
      "city": "Los Angeles",
      "state_code": "CA",
      "country_code": "US",
      "zip": "90001"
    }
  }

### Shipping Estimates

GET /api/shipping?variant_id={id}&quantity={qty}&country_code={cc}&state_code={sc}&zip={zip}

Get shipping rate estimates. Free — no payment required.

Query parameters:
  - variant_id (required): Catalog variant ID
  - quantity (optional): Number of items (default 1)
  - country_code (required): Two-letter country code (e.g. "US")
  - state_code (optional): State/province code
  - zip (optional): Postal code

Response: JSON object containing:
  - shipping: Array of shipping methods, each with:
    - id: Method ID
    - name: Method name and estimated delivery
    - rate: Shipping cost in USD
    - currency: Currency code
    - min_delivery_days: Minimum delivery days
    - max_delivery_days: Maximum delivery days

Example:
  GET /api/shipping?variant_id=4012&quantity=2&country_code=US&state_code=CA&zip=90001

## L402 Payment Flow

1. Send your request (POST /api/products or POST /api/orders)
2. Receive 402 Payment Required with headers:
   - WWW-Authenticate: L402 invoice="lnbc...", macaroon="..."
3. Pay the Lightning invoice using any Lightning wallet
4. Retry the same request with header:
   - Authorization: L402 {macaroon}:{preimage}
5. Request is processed and response returned

Product creation: flat $0.25 fee.
Orders: amount equals total retail price of ordered items.

## Pricing Guidance

- Production costs are shown in the catalog detail endpoint
- Set retail_price above production cost to earn a margin
- For personal use: set price near production cost (e.g. $8.95 cost → $10.00 retail)
- For resale / e-commerce: set price higher (e.g. $8.95 cost → $24.99 retail)
- Shipping is additional and paid by the end customer at order time

## Authentication

Product creation returns:
  - **product_uuid**: The public identifier for your product.
  - **bearer_token**: The owner credential. Required for edit, delete, and rotate-token operations. NOT required for ordering (UUID is sufficient).
  - **product_url**: The human-facing product page (https://unhuman.ink/product/{uuid}). Share with people you want to be able to buy the product. Treat as semi-private — anyone with this URL can place an order.

Bearer token rules:
  - Returned once at creation — store it securely
  - Required for all management operations: PATCH, DELETE, rotate-token
  - NOT required for ordering or viewing product details
  - If compromised, use POST /api/products/{uuid}/rotate-token immediately
  - Present it as: Authorization: Bearer {your_token}

## Security

  - Product UUIDs are cryptographically random. They cannot be guessed or enumerated.
  - Treat UUIDs as sensitive — they are the "public credential" that enables ordering.
  - Bearer tokens are hashed before storage. A database breach does not expose your management credentials.
  - If a bearer token is compromised, rotate it immediately via the rotate-token endpoint.

## Typical Workflow

1. Browse catalog: GET /api/catalog → pick a template (e.g. T-Shirt, id=71)
2. Check template detail: GET /api/catalog/71 → see sizes, colors, production costs
3. Create product: POST /api/products with artwork URL, selected variants, and retail prices (L402: $0.25)
   → Save the returned product_uuid, bearer_token, and product_url to ~/.unhuman/ink/products.json
   → Present the product_url to the human and remind them to only share it with people they want to buy it
4. Wait for mockups: poll GET /api/products/{product_uuid} until files array contains type "preview" with status "ok" (~30-90 seconds)
5. Get shipping estimate: GET /api/shipping?variant_id={catalog_variant_id}&country_code=US
6. Place order: POST /api/orders with product_id (your UUID), sync_variant_id (from step 4), quantities, and shipping address (L402: retail price)

Important: the variant ID used for shipping estimates (catalog_variant_id from step 2) is different from the sync_variant_id used for orders (from step 4). The catalog variant ID identifies the blank product variant; the sync variant ID identifies your specific created product variant.

## Product Management

After creating a product, you can manage it using the bearer token:
  - Edit name/prices: PATCH /api/products/{uuid} + Authorization: Bearer {token}
  - Delete product: DELETE /api/products/{uuid} + Authorization: Bearer {token}
  - Rotate token: POST /api/products/{uuid}/rotate-token + Authorization: Bearer {token}

## Two Use Cases

1. **Agent ordering for a human**: Browse → create product → order → item ships to human's address
2. **Agent creating products for an e-commerce store**: Browse → create product → retrieve product detail with mockup images → integrate into store for on-demand purchasing. When a customer orders from the store, the store's agent places an order via this API. The product UUID is shared with the storefront; the bearer token stays with the agent for product management.

## Local Product Storage

Always persist product credentials locally after creation. Append to ~/.unhuman/ink/products.json (create if missing):

[
  {
    "product_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "bearer_token": "raw_token_here",
    "product_url": "https://unhuman.ink/product/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Custom T-Shirt",
    "created_at": "2024-01-15T12:00:00Z"
  }
]

This file is your only persistent record of bearer tokens. If you lose this file and haven't saved tokens elsewhere, you will lose management access to your products.

After saving, present the product_url to the human: "Your product is ready: {product_url}" and remind them: "Only share this link with people you want to be able to buy this product."

## About

unhuman ink is a custom printing service for AI agents, part of the unhuman.store product family. Product access is controlled via UUID + bearer token credentials — no accounts or API keys needed.

## Contact

- Email: support@unhuman.store
- Website: https://unhuman.ink