Shots API Authentication
Shots has two API surfaces. Editor utility endpoints such as /api/screenshot require a signed-in session or a workspace API key with the artifact:read scope, and per-IP limits apply on top. Versioned /api/v1 tenant endpoints require a workspace API key with the declared scope or a signed-in user session with the matching permission. Create a workspace API key in Settings → Developer API (/workspace/developers).
Editor utility endpoints
The utility endpoints listed below accept a signed-in session, which is how the editor calls them, or a workspace API key with the artifact:read scope in X-API-Key. A request with neither returns 401 with code unauthorized. There is no free plan: a workspace without an active plan gets 403 with code workspace_feature_not_entitled. A complete capture request looks like this:
curl -X POST https://shots.playbookmedia.io/api/screenshot \
-H "X-API-Key: $SHOTS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'Tenant API credentials
Calls to /api/v1 operate on workspace data. Machine callers send an organization key in X-API-Key. Browser callers may use their signed-in session. The server checks workspace membership, role permission, API-key scope, plan feature, and quota where the operation requires them.
curl https://shots.playbookmedia.io/api/v1/releases \
-H "X-API-Key: $SHOTS_API_KEY"Rate limits
| Endpoint | Limit | Notes |
|---|---|---|
| POST /api/screenshot | 20 requests per minute per IP | Returns 429 with Retry-After and X-RateLimit-* headers. |
| POST /api/export | Unmetered | Bounded by request body size and server processing time. |
| GET /api/tweet/{id} | Unmetered | Bounded by the upstream syndication API. |
| GET /api/image-proxy | Unmetered | Restricted to an allowlist of Twitter media hosts. |
Handling 429
When the limit is exceeded the response carries Retry-After in seconds alongside X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Wait for Retry-After before retrying.
{
"error": "Rate limit exceeded. Please try again later.",
"code": "rate_limited",
"message": "Rate limit exceeded. Please try again later.",
"hint": "Wait 42 seconds, then retry. This endpoint allows 20 requests per minute per IP address.",
"status": 429,
"documentation": "https://shots.playbookmedia.io/docs#errors",
"retryAfter": 42
}Credentialed maintenance endpoints
A small number of cache-maintenance endpoints require a shared secret held by the maintainers. They are internal operations and are deliberately absent from the OpenAPI specification.
Next steps
Read the full API documentation, browse the developer portal, or fetch the OpenAPI 3.1 specification.