The public API

Quickstart

For an approved platform, a proof takes four steps.

1. Get a connector key: write to the contact address below. Keep the key on your server.
2. Start a proof: POST the pet photo, a style id from /api/v1/styles and the user's email address. The answer is 202 with the proof's id.
3. Poll the proof: GET it every few seconds until its status is ready or failed.
4. Show the result: imageUrl is the proof image, and checkoutUrl is our page where the user sees it on a canvas print or a phone case and pays.

Live endpoints

Each is a GET request that returns JSON and may be called from any origin. The responses are static files, refreshed when the site is rebuilt and cacheable for five minutes.

• GET /api/v1 What this API is, its endpoints, its documentation and its contact.
• GET /api/v1/styles The portrait styles on offer, with sample images and each style's page.
• GET /api/v1/products Canvas sizes and phone-case styles with exact prices, and the shipping countries.
• GET /api/v1/openapi.json This API described in OpenAPI 3.1.

OpenAPI 3.1 description

Example

curl https://pawforgeart.com/api/v1/products

const res = await fetch("https://pawforgeart.com/api/v1/styles");
const { styles } = await res.json();

A shortened response from the products endpoint:

{
  "currency": "USD",
  "canvas": {
    "sizes": [
      {
        "label": "12\" × 16\"",
        "widthIn": 12,
        "heightIn": 16,
        "orientation": "vertical",
        "priceCents": 6000
      }
    ]
  },
  "phoneCase": {
    "styles": [
      {
        "id": "impact",
        "label": "Impact-resistant case",
        "priceCents": 4500
      }
    ],
    "devices": null
  },
  "shipping": {
    "countryCount": 32,
    "countries": [
      {
        "code": "US",
        "name": "United States"
      },
      {
        "code": "CA",
        "name": "Canada"
      }
    ]
  }
}

We ship to 32 countries, listed in the products endpoint.

Authentication

The read endpoints are open: no key and no account. The proof endpoints need a connector key, sent in the X-PawForge-Key header; we issue keys to approved platforms.

Keep the key on your server: the routes send no CORS headers, so a browser cannot call them.

Proof API, for approved platforms

Two keyed endpoints on https://api.pawforgeart.com: start a free proof from a pet photo, then read it back. A ready proof carries a link to our checkout page, which shows the product preview; purchases complete through our Stripe checkout. There is no public sign-up for a key.

Live for approved platforms: callable only with a connector key the studio issues. There is no public sign-up; write to the contact address to be considered.

curl -X POST https://api.pawforgeart.com/api/v1/proofs \
  -H "X-PawForge-Key: $PAWFORGE_KEY" \
  -F photo=@pet.jpg \
  -F styleId=roman_emperor \
  -F email=someone@example.com \
  -F orientation=vertical

{
  "id": "<proof id>",
  "status": "processing"
}

curl https://api.pawforgeart.com/api/v1/proofs/<proof id> \
  -H "X-PawForge-Key: $PAWFORGE_KEY"

{
  "id": "<proof id>",
  "status": "ready",
  "styleId": "roman_emperor",
  "imageUrl": "<proof image URL>",
  "checkoutUrl": "<our checkout page URL>",
  "reason": null
}

Proof statuses

GET reports one of three statuses.

Errors

Every error is JSON of the form {"error": "<code>"}. A 400 also names the form field at fault, when there is one.

Example error

{
  "error": "invalid_request",
  "field": "styleId"
}

Limits

Versioning

This is version 1.2.0, and the paths carry /api/v1. This page and the OpenAPI document read their fields, limits and error codes from the same code the API runs, so they change when it does.