Projects

Use projects when your integration needs more than a one-off export request.

Typical cases:

• browser or desktop editors with autosave
• multi-step pipelines that upload assets first and render later
• retry-safe workflows where task history should stay attached to one project

When To Use Projects

Prefer /v1/projects when you need to:

• keep editorState on the server
• update title and description independently from autosave traffic
• upload assets before final render
• create multiple export tasks from the same saved project

If you only need a single render and do not need to save project state, stay with POST /v1/exports.

Projects vs. Stateless Exports

Use POST /v1/projects/{projectId}/exports when you want to render the latest saved project state.

Use POST /v1/exports when you want to submit a full editorState payload and render it immediately without creating a project.

Lifecycle Overview

1. Create a project with POST /v1/projects
2. Read the full project with GET /v1/projects/{projectId}
3. Update metadata with PATCH /v1/projects/{projectId}
4. Replace the latest editorState with POST /v1/projects/{projectId}/sync
5. Export the saved project with POST /v1/projects/{projectId}/exports
6. Delete the project with DELETE /v1/projects/{projectId}

Metadata vs. Autosave

• PATCH /v1/projects/{projectId} updates only title and description
• POST /v1/projects/{projectId}/sync updates only editorState and stateVersion
• GET /v1/projects/{projectId} returns both metadata and the latest persisted editorState

sync is designed for autosave. each call replaces the stored editorState with the provided payload.

Sync Rate Limits

POST /v1/projects/{projectId}/sync is designed for periodic autosave. avoid calling it on every input event.

If the API returns 429 OPEN_API_PROJECT_SYNC_RATE_LIMITED, back off and retry with jitter.

Project Export Tracking

Project-based exports return the same task structure as stateless exports, plus an optional projectId.

That projectId also appears in:

• GET /v1/exports
• GET /v1/exports/{taskId}
• export webhook payloads

Use it to correlate task history back to one project.

Runtime Access

Project routes require runtime OpenAPI access.

If the current account is not eligible for these routes, the API returns 403 OPEN_API_RUNTIME_ACCESS_FORBIDDEN.