What the public /v1 API can do

public api

The creativehub public API lets your own software upload artwork, build and publish drops, and place orders. Requests go to https://escher-v2.creativehub.io/v1 with an esch_live_ bearer token — see How to create API tokens for the public /v1 surface to get one.

Documentation

The API documentation is public at https://sell.creativehub.io/api-docs (https://api.creativehub.io also takes you there). The full /v1 surface is also described at the OpenAPI endpoint (/openapi.json on the API service).

The endpoint groups

  • Uploads — POST /v1/uploads (a file), POST /v1/uploads/ref (an image by URL), upload sessions (POST /v1/uploads/sessions, …/sessions/complete), POST /v1/uploads/link (a temporary link where someone drops files in a browser), GET /v1/uploads, GET /v1/uploads/{id}.
  • Drops — POST /v1/drops, GET /v1/drops, GET / PATCH / DELETE /v1/drops/{drop_id}, POST /v1/drops/{drop_id}/assets (logo, signature, letter).
  • Products — POST /v1/drops/{drop_id}/products, PUT /v1/drops/{drop_id}/products/{product_id}/variants, DELETE …/products/{product_id}; GET /v1/products, GET /v1/products/{id}, GET /v1/products/{id}/variants.
  • Recommendations — POST /v1/recommendations (a drop), POST /v1/drops/{drop_id}/products/{product_id}/recommendations (one artwork).
  • Page styles — GET /v1/styles/schema, GET /v1/styles, POST /v1/styles/extract (returns five variations to choose from), GET /v1/styles/variations/{id}, POST /v1/styles, GET / PATCH / DELETE /v1/styles/{style_id}, POST /v1/drops/{drop_id}/style-preview (a 15-minute preview link).
  • Publishing — POST /v1/drops/{drop_id}/publish, GET /v1/drops/{drop_id}/publish-attempts/latest.
  • Orders and invoices — POST /v1/orders/quote, POST /v1/orders, GET /v1/orders, GET /v1/orders/{id}, GET /v1/invoices, GET /v1/invoices/{id}.

Uploading files

You can upload files directly. POST /v1/uploads takes the file's bytes as the request body: the body is the raw file, not a multipart form. It accepts JPEG, PNG or TIFF up to 2 GB and needs a Content-Length header; a multipart form is refused with HTTP 415.

If the image is already hosted, register it by its public URL with POST /v1/uploads/ref instead. Upload sessions (/v1/uploads/sessions) and upload links (/v1/uploads/link) are the other two routes.

Check your images yourself

There is no preflight endpoint for dpi, dimensions, aspect ratio or colour profile. Validate each image in your own backend before ordering, and prepare it at the exact image area you want printed.

For what a print-ready file looks like, how to photograph or scan your artwork has four checks that show whether a file is good enough.

Borders on variants

Borders set through the API are presets only: none, small or large. You can't set a border per side.

Before you automate a release, it helps to see one from the buyer's side: the print drops page shows how a time-limited sale looks and runs.

Still need a hand?

Ask the in-app help assistant from your creativehub dashboard, or email us — a real person replies. info@creativehub.io