Templates & brand endpoints

Templates#

Search the template library and turn a template into a new design.

Search templates#

GET/templates

Convex templates.search · templates.listScope templates:read

Search by prompt-like text, or list by kind and category. Premium templates are marked and require Pro to instantiate.

Parameters

qstringQuery

Free text, e.g. minimal bakery menu.

kindDesignKindQuery

Filter by kind.

categorystringQuery

Filter by category.

limitintegerQuery

1–60, default 24.

cursorstringQuery

Pagination cursor.

Shell

curl "https://api.desyn.app/api/v1/templates" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "items": [
    {
      "slug": "bakery-menu-warm",
      "title": "Warm bakery menu",
      "kind": "menu",
      "category": [
        "food"
      ],
      "premium": false,
      "thumbnailUrl": "https://files.desyn.app/templates/bakery-menu-warm.webp"
    }
  ],
  "nextCursor": null
}

Get a template#

GET/templates/{slug}

Convex templates.getScope templates:read

Template metadata including its slots (named layers meant to be replaced, such as headline or photo).

Parameters

slugstringPathRequired

Template slug.

Shell

curl "https://api.desyn.app/api/v1/templates/$SLUG" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "slug": "bakery-menu-warm",
  "title": "Warm bakery menu",
  "kind": "menu",
  "premium": false,
  "pages": 1,
  "slots": [
    "title",
    "subtitle",
    "item-1",
    "price-1",
    "photo"
  ]
}

Instantiate a template#

POST/templates/{slug}/instantiate

Convex templates.instantiateScope designs:write

Creates a new design from the template, optionally filling slots and applying a brand kit in the same step.

Parameters

slugstringPathRequired

Template slug.

namestringBody

Name of the new design.

slotsRecord<string, string>Body

Text for text slots, asset ids for image slots.

brandKitIdstringBody

Apply this brand kit.

Shell

curl -X POST "https://api.desyn.app/api/v1/templates/$SLUG/instantiate" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Menu — autumn",
  "slots": {
    "title": "Autumn menu",
    "photo": "a9b8c7d6e5f4"
  }
}'

201 Created

{
  "id": "k1dd2ee3ff4gg5hh6ii7jj8kk2",
  "name": "Menu — autumn",
  "kind": "menu",
  "workspaceId": "j57a1b2c3d4e5f6g7h8i9j0k1m",
  "folderId": null,
  "seq": 2,
  "pageCount": 3,
  "thumbnailUrl": "https://files.desyn.app/thumbs/k17c2v9m3n8q4r5s6t7u8w9x0y/128.webp?sig=…",
  "archived": false,
  "updatedAt": 1792483200000
}

Brand kits & folders#

Brand kits drive apply_brand and brand-aware generation; folders organize designs.

List brand kits#

GET/brand-kits

Convex brandKits.listScope brand:read

Brand kits of the workspace.

Parameters

workspaceIdstringQuery

Defaults to the key's workspace.

Shell

curl "https://api.desyn.app/api/v1/brand-kits" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "items": [
    {
      "id": "b1c2d3e4f5a6",
      "name": "Sunline Coffee",
      "colors": [
        {
          "name": "Ember",
          "value": "#ff6a1f"
        },
        {
          "name": "Cream",
          "value": "#f6efe3"
        }
      ],
      "fonts": [
        {
          "role": "heading",
          "family": "Instrument Serif"
        },
        {
          "role": "body",
          "family": "Instrument Sans"
        }
      ],
      "logos": [
        "a1l2o3g4o5x6"
      ],
      "voice": "Warm, unhurried, a little poetic. Never shouty."
    }
  ]
}

Create a brand kit#

POST/brand-kits

Convex brandKits.createScope brand:write

Create a kit from explicit values. Requires the brandKit feature (Pro or self-hosted).

Parameters

namestringBodyRequired

Kit name.

colors{ name, value }[]Body

Palette in order of importance.

fonts{ role, family, weight? }[]Body

Roles: heading, subheading, body, accent.

logosstring[]Body

Asset ids.

voicestringBody

Tone of voice for AI copy.

rulesstring[]Body

Hard rules, e.g. Never place the logo on photos.

Shell

curl -X POST "https://api.desyn.app/api/v1/brand-kits" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Sunline Coffee",
  "colors": [
    {
      "name": "Ember",
      "value": "#ff6a1f"
    }
  ],
  "voice": "Warm, unhurried."
}'

201 Created

{
  "id": "b1c2d3e4f5a6",
  "name": "Sunline Coffee"
}

Update a brand kit#

PATCH/brand-kits/{brandKitId}

Convex brandKits.updateScope brand:write

Replace any of the fields listed under create. Designs that follow the kit are not changed until you apply it again.

Parameters

brandKitIdstringPathRequired

Brand kit id.

Shell

curl -X PATCH "https://api.desyn.app/api/v1/brand-kits/$BRAND_KIT_ID" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "voice": "Warm, unhurried, a little poetic."
}'

200 OK

{
  "id": "b1c2d3e4f5a6",
  "name": "Sunline Coffee"
}

Delete a brand kit#

DELETE/brand-kits/{brandKitId}

Convex brandKits.deleteScope brand:write

Deletes the kit. Designs keep their current styling.

Parameters

brandKitIdstringPathRequired

Brand kit id.

Shell

curl -X DELETE "https://api.desyn.app/api/v1/brand-kits/$BRAND_KIT_ID" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "deleted": true
}

List folders#

GET/folders

Convex folders.listScope designs:read

Folders of the workspace as a flat list with parentId.

Parameters

workspaceIdstringQuery

Defaults to the key's workspace.

Shell

curl "https://api.desyn.app/api/v1/folders" \
  -H "Authorization: Bearer $DESYN_API_KEY"

200 OK

{
  "items": [
    {
      "id": "f1o2l3d4e5r6",
      "name": "Spring launch",
      "parentId": null
    }
  ]
}

Create a folder#

POST/folders

Convex folders.createScope designs:write

Create a folder, optionally nested.

Parameters

namestringBodyRequired

Folder name.

parentIdstringBody

Parent folder.

Shell

curl -X POST "https://api.desyn.app/api/v1/folders" \
  -H "Authorization: Bearer $DESYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Spring launch"
}'

201 Created

{
  "id": "f1o2l3d4e5r6",
  "name": "Spring launch",
  "parentId": null
}