Introduction
Overview of the Roastify API - concepts, base URL, authentication, and key technical details
Welcome to the Roastify API
The Roastify API enables Base and Pro members to automate artwork generation, order submission, catalog access, webhooks, and fulfillment. It is designed for ecommerce platforms, creator tools, and custom applications. The headless creation flow is Create Artwork followed by Create Order; there is no Create Product endpoint for adding a product to the Merchant App catalog.
Quickstart Guide
Get up and running in minutes with step-by-step instructions for enabling API access and making your first request.
API Reference
Explore all available endpoints, request/response formats, and parameters.
Base URL
All API requests should be made to:
https://api.roastify.app/v1Authentication
Authenticate every request by including your API key in the x-api-key header:
curl https://api.roastify.app/v1/catalog/products \
-H "x-api-key: YOUR_API_KEY"Need an API key? Follow our Quickstart Guide to enable API access and generate your keys.
Test vs Live Environments
Roastify provides separate environments for development and production:
| Environment | API Key Prefix | Purpose |
|---|---|---|
| Test | rty_test_ | Sandbox for development - orders are not fulfilled |
| Live | rty_live_ | Production - real orders that will be fulfilled |
Always develop and test with a Test key first. Only switch to your Live key when you're ready for production.
Rate Limiting
Requests are rate limited to 100 requests per minute per API key. Exceeding this limit returns a 429 Too Many Requests error.
If you need higher limits for production use, contact us at support@roastify.app.
Error Handling
The API uses standard HTTP status codes:
| Status Code | Meaning |
|---|---|
2xx | Success |
400 | Bad Request - Invalid input |
401 | Unauthorized - Invalid or missing API key |
403 | Forbidden - A paid plan or resource access is required |
404 | Not Found - Resource doesn't exist |
422 | Validation Error - Request data failed validation |
429 | Too Many Requests - Rate limit exceeded |
5xx | Server Error - Something went wrong on our end |
Error responses include a JSON body with message and code fields:
{
"code": 401,
"message": "No API Integration found."
}Pagination
The user-products and orders list endpoints use cursor-based pagination with a default page size of 20 items. The catalog-products endpoint returns an unpaginated array.
| Parameter | Type | Description |
|---|---|---|
pageSize | number | Number of items per page (default: 20) |
cursor | string | Cursor for the next page of results |
Response includes:
| Field | Type | Description |
|---|---|---|
pageInfo.endCursor | string | Cursor to use for the next page |
pageInfo.hasNextPage | boolean | Whether another page of results is available |
Currency
All monetary values are represented in cents (the smallest currency unit). For example, 2400 represents $24.00 USD.
Idempotency
For POST requests, include an Idempotency-Key header to safely retry requests without creating duplicates:
curl -X POST https://api.roastify.app/v1/orders \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: unique-request-id-123" \
-H "Content-Type: application/json" \
-d '{ ... }'See the Idempotency Guide for details.