Blog

Before you can generate a dieline or create a 3D mockup, you need to find the template that matches the box you want. This post walks through the three discovery endpoints, explains how main templates and their variations relate, and shows the exact requests you need to go from "I want a tuck end box" to "I have the template ID".

The examples below use curl, which is a command you run in a terminal (Terminal on macOS or Linux, Command Prompt or PowerShell on Windows). If you prefer a graphical client, paste the same URL, headers, and body into Postman or Insomnia. Both are free and friendlier for first-time API testing.

Discovery requests do not consume API credits. The examples below use the production base URL https://api.diecuttemplates.com; the sandbox at https://sandbox.api.diecuttemplates.com works identically if you prefer to test there.

Finding a template is a three-step drill-down:

1. List the groups — every group in the catalog (e.g. "Tuck End Boxes", "Tray Boxes"). Every group belongs to one of three categories: Cartons, Corrugated Cardboards, or Hard Cardboards.
2. List the templates in a group — get paginated summaries of every main template that belongs to that group.
3. Fetch a single template — get the full definition: variables you can set, dimensions, images, and the links that lead to its variations.

Steps 1 and 2 narrow the catalog down to a manageable list. Step 3 is where you decide whether a specific template is the right one and where you discover its variations.

A group is something like "Tuck End Boxes" or "Tray Boxes". Every group has a category field — there are only three categories in the catalog: Cartons, Corrugated Cardboards, and Hard Cardboards. The endpoint returns every group in a single response; there is no pagination on it.

curl -X GET \
  https://api.diecuttemplates.com/dieline-template-groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Dielines-Api-Version: 1.0"

A trimmed response looks like this:

{
  "dieline_template_group_list": {
    "type": "dieline_template_group_list",
    "dieline_template_groups": [
      { "type": "dieline_template_group", "id": "cartons_food_boxes",        "name": "Food Boxes",     "category": "Cartons" },
      { "type": "dieline_template_group", "id": "cartons_tuck_end_boxes",    "name": "Tuck End Boxes", "category": "Cartons" },
      { "type": "dieline_template_group", "id": "corrugated_cardboards_tray_boxes",
        "name": "Tray Boxes", "category": "Corrugated Cardboards" }
    ]
  }
}

The id field (for example cartons_tuck_end_boxes) is what you pass as group_id in step 2. The category field is one of the three category names — useful if you want to bucket the groups in your own UI.

Now narrow the catalog to a single group. The list endpoint has two modes — you can either get lightweight summaries (the default), or get the full template for every entry inline by passing expand=true. Which one you want depends on what you are building.

Each entry is a dieline_template_summary — just enough to render a thumbnail card and let a user pick one. It contains:

• id — the template id you use in step 3.
• group_id — which group the template belongs to.
• images — a small PNG, a large PNG, and an SVG of the dieline.
• links — pointers to fetch the full template in mm or in, plus the template's public web page.

What is not here: the input variables you would need to send when generating a dieline, the structural metadata (flap, tuck, dust flap, hang hole), and the variation links. For those you need to follow a dieline_template link to step 3.

curl -X GET \
  "https://api.diecuttemplates.com/dieline-templates?group_id=cartons_tuck_end_boxes" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Dielines-Api-Version: 1.0"

A trimmed response:

{
  "dieline_template_list": {
    "type": "dieline_template_list",
    "total": 35,
    "page": 1,
    "page_size": 25,
    "dieline_templates": [
      {
        "type": "dieline_template_summary",
        "id": "becf-10301",
        "group_id": "cartons_tuck_end_boxes",
        "images": [
          { "type": "png", "size": "small", "url": "https://.../small.png" },
          { "type": "png", "size": "large", "url": "https://.../large.png" },
          { "type": "svg",                   "url": "https://.../template.svg" }
        ],
        "links": [
          { "rel": "dieline_template", "href": "/dieline-templates/mm/becf-10301", "method": "GET", "unit": "mm" },
          { "rel": "dieline_template", "href": "/dieline-templates/in/becf-10301", "method": "GET", "unit": "in" },
          { "rel": "web",              "href": "https://www.diecuttemplates.com/dielines/37101/tuck-end-boxes-becf-10301", "method": "GET" }
        ]
      }
    ],
    "links": [
      { "rel": "self",      "href": "/dieline-templates?group_id=cartons_tuck_end_boxes&page=1&page_size=25", "method": "GET" },
      { "rel": "next_page", "href": "/dieline-templates?group_id=cartons_tuck_end_boxes&page=2&page_size=25", "method": "GET" }
    ]
  }
}

Pass expand=true and each entry becomes a full dieline_template instead of a summary — the same shape you get back from step 3, for every template in the page. That includes:

• group — the full group object (id, name, category), not just the group_id string.
• flap, tuck, dust_flap, hang_hole, tags — the structural metadata that describes which kind of tuck, flap, etc. this template uses.
• variables — every input variable (length, width, height, material, optional toggles) with its data type, whether it is required, default value, and a labeling image.
• links — self, web, plus every variation link reachable from this template (add_*, remove_*, change_* — see step 3 for what those mean).

unit is required when expand=true (mm or in):

curl -X GET \
  "https://api.diecuttemplates.com/dieline-templates?group_id=cartons_tuck_end_boxes&expand=true&unit=mm" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Dielines-Api-Version: 1.0"

• Building a browsing UI? Use summary mode. You only need the thumbnail and the id; the response is small and a single page renders fast.
• Building a generator or running analysis over the catalog? Use expand=true so you have variables and structural metadata for every template without a second round-trip per item.

Both modes paginate the same way. Use page and page_size (max 100) to walk through large groups. The links array at the bottom of the response includes self, previous_page, and next_page — follow them rather than constructing URLs by hand.

Once you have a template id, fetch its full definition. The URL takes a unit segment (mm or in) and the template id:

curl -X GET \
  https://api.diecuttemplates.com/dieline-templates/mm/becf-10301 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Dielines-Api-Version: 1.0"

A trimmed response:

{
  "dieline_template": {
    "type": "dieline_template",
    "id": "becf-10301",
    "group": { "type": "dieline_template_group", "id": "cartons_tuck_end_boxes", "name": "Tuck End Boxes", "category": "Cartons" },
    "flap":       { "type": "flap",       "id": "uni_tuck_flap",          "image": "https://.../flap_4.png" },
    "tuck":       { "type": "tuck",       "id": "sit_lock_tuck",          "image": "https://.../tuck_4.png" },
    "dust_flap":  { "type": "dust_flap",  "id": "slit_lock_dust_flap",    "image": "https://.../dust_flap_4.png" },
    "variables": [
      { "name": "length", "data_type": "length",  "required": true,  "image": { "type": "svg", "url": "https://.../length.svg" } },
      { "name": "width",  "data_type": "length",  "required": true,  "image": { "type": "svg", "url": "https://.../width.svg" } },
      { "name": "height", "data_type": "length",  "required": true,  "image": { "type": "svg", "url": "https://.../height.svg" } },
      { "name": "overflow", "data_type": "boolean", "required": false, "default_value": { "value": false } }
    ],
    "links": [
      { "rel": "self",                   "href": "/dieline-templates/mm/becf-10301", "method": "GET" },
      { "rel": "web",                    "href": "https://www.diecuttemplates.com/dielines/37101/tuck-end-boxes-becf-10301", "method": "GET" },
      { "rel": "add_top_postal_lock",    "href": "/dieline-templates/mm/becf-1031b", "method": "GET" },
      { "rel": "add_top_thumb_cut",      "href": "/dieline-templates/mm/becf-10319", "method": "GET" },
      { "rel": "add_hanger_tab",         "href": "/dieline-templates/mm/becf-1030d", "method": "GET" },
      { "rel": "add_bottom_postal_lock", "href": "/dieline-templates/mm/becf-1031c", "method": "GET" },
      { "rel": "add_bottom_thumb_cut",   "href": "/dieline-templates/mm/becf-1031a", "method": "GET" },
      { "rel": "change_flap",            "name": "friction_fit_tuck_in_flap", "href": "/dieline-templates/mm/becf-10307", "method": "GET" },
      { "rel": "change_dust_flap",       "name": "full_angled_dust_flap",     "href": "/dieline-templates/mm/becf-10304", "method": "GET" }
    ]
  }
}

Two parts of this response do most of the work:

• variables tells you which fields you have to send when you generate a dieline from this template (see the 3D mockups walkthrough for the POST /dieline-templates/{id}/dielines call). Variables marked required: true must be present in your request body; the rest fall back to default_value.
• links is how you discover variations — see the next section.

One detail worth calling out explicitly:

The list endpoint only returns main templates. Every variation of a main template — same body, different flap, an extra hang hole, a postal lock added to the lid — is a separate template with its own id, and it does not appear in GET /dieline-templates. You reach variations by following the link rels on the main template's response.

In the example above, becf-10301 is the main "Sit Lock Tuck / Uni Tuck Flap / Slit Lock Dust Flap" tuck end box. Its links array advertises every variation the catalog has of it:

• add_top_postal_lock, add_top_thumb_cut, add_hanger_tab — the same box with one structural feature added. Each link points to a different template id.
• change_flap, change_dust_flap — the same box with the flap or dust flap swapped for an alternative. The name field on the link (e.g. friction_fit_tuck_in_flap) tells you which alternative it leads to.

Each variation link is itself a fetchable template URL. Follow it with another GET and you get a full dieline_template for that variation — including its own links, which expose further variations from that point. In other words, variations form a graph: you discover the catalog by walking it.

If you want to enumerate every link in links, the safest filter is "not self and not web": self points to the current template, web points to its public page, and everything else is a variation. Variation rels include prefixes like add_*, remove_*, and change_* (for example change_flap, change_dust_flap, change_cover, change_hang_hole).

Three requests cover the whole discovery surface:

1. GET /dieline-template-groups — returns every group id in the catalog.
2. GET /dieline-templates?group_id={id}&page={n}&page_size={n} — returns paginated dieline_template_summary entries for that group. Add expand=true&unit=mm if you want the full shape inline.
3. GET /dieline-templates/{mm|in}/{template_id} — returns the full template plus the links array that exposes its variations.

Once you have the template id you want, head over to the 3D mockups walkthrough to generate a dieline and attach artwork. Full reference docs live at Dielines API — Getting Started; pricing is at API pricing.

If you hit anything unexpected while exploring the Sandbox, send us the request you are making and the response you are getting and we will take a look.