Introduction
Overview of the Roastify API - concepts, base URL, authentication, and key technical details
Welcome to the Roastify API
The Roastify API enables you to build, customize, and automate coffee product creation, order fulfillment, and more. Designed for seamless integration with e-commerce platforms, creator tools, and custom applications, the API provides robust endpoints for managing products, artwork, orders, and fulfillment.
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 |
404 | Not Found - Resource doesn't exist |
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:
{
"message": "Invalid API key",
"code": "UNAUTHORIZED"
}Pagination
Endpoints that return multiple items use cursor-based pagination with a default page size of 20 items.
| 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 |
|---|---|---|
nextCursor | string | Cursor to use for the next page |
hasMore | boolean | Whether more results are 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.