# 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

Example:
  GET /api/catalog/71

### Create Product

POST /api/products

Create a product with custom artwork. This endpoint is L402-protected — flat $2.00 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)
  - artwork_url: Public URL to artwork image (PNG recommended, min 150 DPI)
  - 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")
  - thumbnail_url (optional): Product thumbnail image URL

Mockup images are generated automatically after product creation. This happens asynchronously and typically takes 30-90 seconds.

Response: JSON object containing:
  - product:
    - sync_product: Product summary with id, name, variants count, synced count
    - sync_variants: Array of created variants with id, name, retail_price, size, color

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

### Product Detail

GET /api/products/{id}

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

Response: JSON object containing:
  - product:
    - sync_product: Product summary (id, name, thumbnail_url)
    - sync_variants: Array of variants, each with:
      - id: Sync variant ID (use this for orders, as sync_variant_id)
      - 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".

You can also view a created product in a browser at: https://unhuman.ink/product/{id}

Example:
  GET /api/products/12345

### 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 ID (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.

Example:
  POST /api/orders
  {
    "product_id": "12345",
    "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 $2.00 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

## 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: $2.00)
4. Wait for mockups: poll GET /api/products/{id} until files array contains type "preview" with status "ok" (~30-90 seconds)
5. View product page: https://unhuman.ink/product/{id} — shows mockups, variants, and prices in a browser
6. Get shipping estimate: GET /api/shipping?variant_id={catalog_variant_id}&country_code=US
7. Place order: POST /api/orders with 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.

## 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.

## About

unhuman ink is a custom printing service for AI agents, part of the unhuman.store product family. No accounts, no API keys — payment is the authentication.

## Contact

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