API Reference
Kontraktr exposes a set of public REST endpoints at https://app.kontraktr.io/api/public/. These power the customer portal, QR scanning, job submissions, art marketplace, and the public quote calculator. No API key is required — access is controlled via customer-specific slug tokens.
Public endpoints use slug-based auth. The customer's unique slug IS the credential.
Submission and login endpoints enforce per-IP rate limits. 429 responses include a Retry-After header.
All endpoints require HTTPS in production. HTTP requests are redirected.
Authentication model
Slug auth — Most portal endpoints use :slug as the credential. Each customer has a unique, unguessable slug. The slug scopes all data to that customer.
Portal JWT — Optional login endpoints issue a short-lived JWT in an HTTP-only cookie. Required only for /portal/auth/* routes.
No auth — Scan, marketplace browse, quote calculator, and discount validation are fully open. No token or slug needed.
Customer Portal
Slug-based public endpoints powering the customer portal. No API key required — the unique customer slug acts as authentication. All portal routes are read/write scoped to a single customer.
Portal Authentication
Optional JWT-based login for customer portal accounts. When enabled, customers log in with email + password and receive a session cookie. This is separate from the slug-based access — slug routes work without authentication.
Job Submission
Endpoints used by the customer-facing quote submission form. Files are uploaded first with a temporary token, then the full job is submitted in one POST which links all uploaded files.
QR Code Scanning
Public job lookup endpoint used by the Kontraktr QR scanner. When a QR code is scanned, authenticated staff are redirected to the job modal; unauthenticated visitors see a public status card.
Art Marketplace
Public art template marketplace. Browse and search published designs without authentication. canvasJson (the Fabric.js design data) is only returned after purchase.
Quote Calculator
Public pricing endpoint. Returns the full pricing matrix (quantity tiers × color counts) used by the customer-facing quote calculator. Can optionally calculate a specific quote.
Discount Codes
Validate discount codes during checkout or quote submission without exposing the full code database.
Job Statuses
Jobs flow through a fixed production pipeline. The status field returned by all job endpoints uses these string values.
| Status value | Label | Description |
|---|---|---|
QUOTE | Quote | New job awaiting shop review |
APPROVED_QUOTE | Approved Quote | Quote accepted by customer |
ART_PENDING | Art Pending | Waiting for customer artwork |
ART_RECEIVED | Art Received | Artwork received, in review |
ART_APPROVAL_SENT | Art Approval Sent | Mockup sent to customer for review |
ART_APPROVED | Art Approved | Customer approved mockups |
ART_DECLINED | Art Declined | Customer declined mockups |
FILMS | Films | Film positives being output |
SCREEN_BURNED | Screen Burned | Screens coated and exposed |
IN_PRODUCTION | In Production | Actively printing |
BAGGING_SIZE_LABELING | Bagging / Labeling | Finishing and packaging |
COMPLETED_ORDER | Completed | Order complete, not yet paid |
COMPLETED_PAID | Completed & Paid | Order complete and invoice paid |
ON_HOLD | On Hold | Job paused |
CANCELLED | Cancelled | Job cancelled |
Rate Limits
All endpoints enforce rate limits at the IP level. When a limit is hit, the server responds with HTTP 429 Too Many Requests and a Retry-After header indicating seconds until retry.
| Endpoint | Limit | Lockout behaviour |
|---|---|---|
POST /api/public/submit | 5 req/min per IP | Retry-After header returned |
POST /api/public/portal/auth/login | 10 req/min per IP | Account locks 15 min after 5 failures |
All other public endpoints | 60 req/min per IP (platform-level) | 429 returned |
Error response envelope
{
"error": "Human-readable error message"
}All error responses return a JSON object with a single error field. Validation errors (400) on the submission endpoint return a semicolon-separated list of all validation failures.