Authentication, errors and retries
Use scoped API keys safely and build predictable error handling.
API keys
Create keys in Studio → Settings → API keys. Send a key on every public V2 API request:
curl "$JSONCUT_API/api/v2/usage" \
-H "X-API-Key: $JSONCUT_API_KEY"Never expose a key in browser JavaScript, a mobile bundle, a public MCP configuration or source control. Use separate keys for development and production, grant only the scopes the integration needs, and rotate a key immediately if it is exposed.
Available V2 scopes are grouped by task:
| Resource | Scopes |
|---|---|
| Projects | projects:read, projects:write, projects:delete |
| Templates | templates:read, templates:write, templates:render, templates:bulk |
| Media | media:read, media:write, media:delete |
| Rendering | renders:create, operations:read, operations:cancel |
| Account resources | usage:read, resources:read |
The API checks every required scope for an operation. A key that can create a project does not automatically gain permission to delete it.
Idempotent rendering
Render creation accepts an Idempotency-Key. Repeating the same request with the same key returns the existing operation instead of billing or rendering it twice.
curl -X POST "$JSONCUT_API/api/v2/projects/$PROJECT_ID/renders" \
-H "X-API-Key: $JSONCUT_API_KEY" \
-H "Idempotency-Key: order-1042-product-video" \
-H "Content-Type: application/json" \
-d '{"kind":"video","format":"mp4","quality":"high"}'Use a stable business identifier, not a new random value for every retry.
Error shape
All public JSON errors use a safe, stable response:
{
"success": false,
"error": "The project contains an unavailable media reference.",
"code": "VALIDATION_FAILED",
"retryable": false,
"requestId": "req_01J..."
}| Code | Typical action |
|---|---|
BAD_REQUEST | Correct the request shape. |
UNAUTHORIZED | Supply a valid API key. |
PAYMENT_REQUIRED | Start or upgrade the required plan, or add the required credits. |
FORBIDDEN | Add the required scope or use the owning workspace. |
NOT_FOUND | Verify the resource ID and tenant. |
CONFLICT | Read the current project version and retry the edit. |
PAYLOAD_TOO_LARGE | Upload media first; replace large Base64 data with its media reference. |
RANGE_NOT_SATISFIABLE | Correct the requested media byte range. |
VALIDATION_FAILED | Correct the project, input values or output combination. |
PRECONDITION_REQUIRED | Supply the current project version through If-Match or the request body. |
RATE_LIMITED | Wait before retrying. |
SERVICE_UNAVAILABLE | Retry with exponential backoff when retryable is true. |
The public response never exposes stack traces, infrastructure names or upstream AI model/provider details. Include requestId when contacting support.
Optimistic project writes
Overwriting project mutations require an exact current version through the If-Match header or the numeric body version. Prefer the header:
curl -X PUT "$JSONCUT_API/api/v2/projects/$PROJECT_ID" \
-H "X-API-Key: $JSONCUT_API_KEY" \
-H 'If-Match: "3"' \
-H "Content-Type: application/json" \
--data @updated-project.jsonA missing version returns 428 Precondition Required. A mismatched version returns 409 Conflict. Reload, preserve the newer work and reapply only the intended change.