Syncing components

The sync recipe

The order that avoids the common mistakes. Artwork first, components second, because components carry image URLs.

1. Choose how artwork gets there

Three options, and the tradeoff is real:

curl -X POST https://dustinsdesignerden.com/api/v1/projects/PROJECT_ID/assets/from-url \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://cdn.example.com/dagger.png"}'

curl -X POST https://dustinsdesignerden.com/api/v1/projects/PROJECT_ID/assets \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@dagger.png"

2. Push components in batches

Up to 500 rows per call, one component type per call. The whole batch is a single transaction.

POST /api/v1/projects/42/components/batch

{
  "type": "card",
  "remove_missing": true,
  "components": [
    {
      "unique_id": "dxt-card-8817",
      "name": "Rusty Dagger",
      "quantity": 3,
      "image_url": "https://.../dagger-front.avif",
      "back_image_url": "https://.../card-back.avif",
      "card_mask_type": "rectangle_rounded",
      "deck_names": ["Weapons", "Starter Deck"]
    }
  ]
}

The response tells you exactly what happened. Per-row problems come back in errors while the valid rows still apply, so always read it:

{
  "created": 1,
  "updated": 0,
  "deleted": 0,
  "errors": [],
  "kept_artwork": [],
  "components": [
    { "id": 918, "name": "Rusty Dagger", "type": "card" }
  ],
  "internalizing": false
}

3. Decks and stacks, including card order

deck_names on a component write is the quick way to drop a card into a deck, but it cannot say what ORDER the deck is in. When order matters, set the whole membership in one call:

PUT /api/v1/projects/42/groups/7/members

{
  "members": [
    { "unique_id": "ext-card-001", "count": 2 },
    { "unique_id": "ext-card-002" },
    { "unique_id": "ext-card-003", "face_up": false }
  ]
}

• Array order is card order. Position is taken from the array, so you never set it by hand.
• Members are identified by your own unique_id, and only that, so you never have to read back an id this API assigned. The lookup is scoped to this project.
• count is how many copies of that component the deck holds. face_up is true for front up and false for face down; leave it out and the entry is dealt however the group is.
• Send "members": [] to empty a deck without deleting any component.
• Deleting a group removes the grouping only. The components stay.

4. Component types

Valid values for type:

Older components may still carry a legacy type (other, piece or cube). Those cannot be created: other was folded into token once tokens could use their own image as a mask. You can still read them, and GET /components?type= accepts them, so you can list the old rows in order to migrate them onto a current type.

5. Picking a shape

Shapes go in card_mask_type (cards) or shape (tokens). Do not hardcode the list: the default: library changes between releases, and every designer has their own custom masks. Fetch the vocabulary instead:

curl https://dustinsdesignerden.com/api/v1/masks \
-H "Authorization: Bearer YOUR_TOKEN"

{
  "card": [
    { "value": "rectangle",    "label": "Rectangle",      "source": "preset", "aspect": null },
    { "value": "flat",         "label": "Hexagon (Flat)", "source": "preset", "aspect": "1:1" },
    { "value": "default:star", "label": "Star",           "source": "preset", "aspect": "1:1" },
    { "value": "custom:8",     "label": "My Swoosh",      "source": "custom", "aspect": "8:7" }
  ],
  "token": [ ... ]
}

• Send value verbatim. rectangle is a card's default.
• source is either preset, a shape the app ships, or custom, one this designer drew in the Mask Editor. Custom masks differ per account, so never hardcode the list.
• aspect is the one ratio each shape carries, written the way ratios are written: 1:1 square, 5:7 a portrait card, 7:5 landscape. It is the ratio the shape was authored at, so divide it yourself if your layout needs a number. null means the shape forces nothing and the component keeps its own physical size. A shaped mask has to force its box, because a hexagon squeezed into a 2.5×3.5 card box is not a hexagon.
• You can also just send a custom mask's name on a component write and it is resolved to the right reference for you.

6. Fields, per component type

Types are not interchangeable. A rulebook row is a page and needs different fields from a card, and size means the die type on dice but a legacy label everywhere else. Each type below lists exactly the fields it honours; anything else you send for that type is ignored.

What each field means

A rulebook, end to end

One row per page. There is no name: the page title goes in page_name, and pages are grouped by book_name.

POST /api/v1/projects/42/components/batch

{
  "type": "rulebook",
  "components": [
    {
      "unique_id": "rb-p1",
      "book_name": "Core Rules",
      "page_name": "Cover",
      "sort_order": 0,
      "image_url": "https://cdn.example.com/rules-01.png"
    },
    {
      "unique_id": "rb-p2",
      "book_name": "Core Rules",
      "page_name": "Setup",
      "sort_order": 1,
      "image_url": "https://cdn.example.com/rules-02.png"
    },
    {
      "unique_id": "rb-p3",
      "book_name": "Core Rules",
      "page_name": "Turn Order",
      "sort_order": 2,
      "image_url": "https://cdn.example.com/rules-03.png"
    }
  ]
}

Dice with custom faces

{
  "type": "dice",
  "components": [
    {
      "unique_id": "die-1",
      "name": "Combat Die",
      "size": "d6",
      "dice_style": "custom",
      "die_faces": [
        "https://cdn.example.com/f1.png",
        "https://cdn.example.com/f2.png"
      ],
      "die_face_labels": ["Hit", "Miss"]
    }
  ]
}

7. What your app can and cannot touch

• Deletes only ever reach components your app created. Hand-made components and other integrations' rows are invisible to your delete calls.
• A locked project refuses every write with 409 project_locked.
• Asset deletes are confined to the project's own folder, so you cannot remove an avatar or another project's art.
• Nothing in the API reaches billing, subscriptions, playtest sessions, feedback, or another designer's data.