Designs vs Workspace Templates
A design always lives in a project. A workspace template belongs to the whole organisation and may optionally sit in a category. That is the whole distinction — and the source of most confusion, because the two look nearly identical over the API.
At a glance
| Design | Workspace template | |
|---|---|---|
| What it is | A live creative inside one project, ready to generate from | An organisation-level master, shared across the workspace |
| Grouped by | a project — always | a category — optional, often none |
| List it with | GET /designs | GET /workspace-templates |
| Filter parameter | project_id | category_id (only matches categorised ones) |
| List the groups with | GET /projects | GET /workspace-template-categories |
| Generate images from it | Yes | No — duplicate it into a project first |
Round-trip via GET /designs/{id}/as-import | Yes | No |
The two listings never overlap. A workspace template will not appear in GET /designs, and a design will not appear in GET /workspace-templates. If a UUID returns 404 on one, try the other — that is usually the whole problem.
Why the grouping is not symmetric
A project is where a design lives; a category is only a folder a workspace template can be filed under. Most workspace templates are in no category at all — they sit at the root of the workspace, which is normal rather than missing data.
Read a workspace template as a variant of a design: the same structure, filed in the workspace library instead of a project, and not generate-ready until you copy it into one. That is why one call creates both — POST /designs/import/json produces a design unless target.kind asks for the workspace variant.
Which one do I have?
- Came from
GET /designs, or lives in a project page in the dashboard → a design. - Came from
GET /workspace-templates, or lives in the Workspace Templates dashboard section → a workspace template. - Created by a design import: you chose. The default
target: { "kind": "design", "project_uuid": … }produces a design;{ "kind": "workspace_template" }produces a workspace template.
Turning a workspace template into a design
That is what duplication is for:
POST /workspace-templates/{companyTemplateId}/use
{ "project_id": "9d1f2b7c-5a44-4c3e-9f21-0b8e6d4a1c73" }The call is asynchronous and returns a duplication_request_id to poll. The result is a design in the project you named — from then on it is addressable through the Designs API like any other. Full reference on the Workspace Templates page.
There is no operation in the other direction: a design cannot be promoted to a workspace template over the API.
A note on category in the Designs API
GET /designs still accepts a category_id filter and still returns category_id / category_name. Those are deprecated aliases of the project fields, kept so existing integrations keep working — on a design they carry the project, not a workspace category.
Prefer project_id / project_name. When both filters are sent, project_id wins.