Create QR code

Persists a code, design snapshot and redirect cache entry, records a creation event and queues a local publication notification for an active code.

Outcome

Persists a code, design snapshot and redirect cache entry, records a creation event and queues a local publication notification for an active code.

Before you start

Verify identity, environment and the intended organization before discovery.
Discover the published codes:write permission and the target policy.
Select an accessible canonical Auth workspace and set WORKSPACE_ID to its returned id. Workspace binding is separate from input.
Review and confirm the exact unchanged plan before execution. Example identifiers grant no live authority.

Discover the target

topolo whoami --json
topolo workspaces list topolo-quro --json
topolo actions get app_topolo_quro.qurocodes.create --detail --json

status_id: Status id discovered through metadata.get with type=statuses.
category_id: Category id discovered through metadata.get with type=categories.
series_id: Series id from series.list, or null when allowed to detach a code. Series membership does not determine workspace access.

Request

POST /qurocodes

Inspect parameters and test this action.

Input fields

Field	Required	Meaning
`url`	Yes	Destination URL. Creating or changing it stores a redirect target; separately verify reachability and printed-code behavior.
`slug`	No	Exact requested or discovered QR slug. Slugs are globally unique; changing one can break distributed printed codes.
`tier`	No	Declared basic, standard or premium tier; listing can also accept all where the input enum allows it. This field is not a pricing or entitlement check.
`status_id`	No	Status id discovered through metadata.get with type=statuses.
`category_id`	No	Category id discovered through metadata.get with type=categories.
`series_id`	No	Series id from series.list, or null when allowed to detach a code. Series membership does not determine workspace access.
`name`	No	Human label for the code or series. Retain the returned identity separately; names need not be unique.
`max_usage`	No	Positive scan threshold for a code; null clears it where the update schema permits. Verify the returned value and scan policy separately.
`valid_from`	No	Start of a code validity window, or null to clear it where permitted by the update schema.
`valid_to`	No	End of a code validity window, or null to clear it where permitted by the update schema.
`design`	No	Discriminated plain/custom/brand design. Plain uses defaults; custom accepts colors and finder/module styles; Brand requires an immutable published kit bound to the workspace. Inspect the returned design and version.

Worked examples

Actual exported Quro Worker with local Miniflare D1/KV and every committed app/analytics migration. Auth, service tokens, Nexus, destination probes and platform archival are synthetic responses; outbound fetch is sealed. Notifications remain in the local outbox. No live redirect propagation, QR scan, destination health, provider delivery, archival or production erasure is established.

Save reviewed input as payload.json, replacing fixture identifiers through discovery.

topolo actions validate app_topolo_quro.qurocodes.create --data @payload.json --json
topolo actions plan app_topolo_quro.qurocodes.create --resource-type workspace --resource-id "$WORKSPACE_ID" --data @payload.json --confirm --json
topolo actions call app_topolo_quro.qurocodes.create --resource-type workspace --resource-id "$WORKSPACE_ID" --data @payload.json --confirm --detail --json

MCP uses the same reviewed input and separately discovered resource binding:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_quro.qurocodes.create",
    "input": {
      "slug": "quro-fixture",
      "url": "https://example.com/fixture",
      "name": "Fixture QR",
      "tier": "standard",
      "series_id": 1,
      "design": {
        "source": "plain"
      }
    },
    "resourceType": "workspace",
    "resourceId": "ws_quro_fixture",
    "confirm": true
  }
}

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_quro.qurocodes.create",
    "input": {
      "slug": "quro-fixture",
      "url": "https://example.com/fixture",
      "name": "Fixture QR",
      "tier": "standard",
      "series_id": 1,
      "design": {
        "source": "plain"
      }
    },
    "resourceType": "workspace",
    "resourceId": "ws_quro_fixture",
    "confirm": true,
    "detail": true
  }
}

Worked response 1 · HTTP 201

Input · payload.json:

{
  "slug": "quro-fixture",
  "url": "https://example.com/fixture",
  "name": "Fixture QR",
  "tier": "standard",
  "series_id": 1,
  "design": {
    "source": "plain"
  }
}

Captured SDK response:

{
  "success": true,
  "data": {
    "slug": "quro-fixture",
    "url": "https://example.com/fixture",
    "tier": "standard",
    "user_id": "user_quro_fixture",
    "organization_id": "org_quro_fixture",
    "workspace_id": "ws_quro_fixture",
    "created_at": "2026-10-06T11:16:12.268Z",
    "series_id": 1,
    "name": "Fixture QR",
    "status_id": 1,
    "category_id": 1,
    "design_version": 1,
    "id": 1,
    "design": {
      "version": 1,
      "source": "plain",
      "foreground": "#000000",
      "background": "#ffffff",
      "moduleStyle": "square",
      "finderStyle": "square",
      "brand": null
    },
    "delivery_mode": "redirect",
    "supports_publishing_state": true,
    "supports_tier_selection": true,
    "management_model": "standard"
  },
  "tier": "standard"
}

HTTP 201. Read the returned id or slug, compare destination, design and tenant. Check the actual redirect and scan before printing; a stored record or queued notification does not prove propagation or delivery.

Worked response 2 · HTTP 409 · Slug already exists

Input · payload.json:

{
  "slug": "quro-fixture",
  "url": "https://example.com/duplicate"
}

Captured SDK response:

{
  "success": false,
  "error": "Slug already exists"
}

HTTP 409. Read the returned reason and current state. A duplicate slug or non-empty workspace must be reconciled before any retry.

Worked response 3 · HTTP 500 · Failed to create QURO code

Input · payload.json:

{
  "url": "https://example.com/brand",
  "design": {
    "source": "brand"
  }
}

Captured SDK response:

{
  "success": false,
  "error": "Failed to create QURO code"
}

HTTP 500. Inspect the handler error and dependencies. A missing published Brand kit currently becomes a generic server failure; do not retry by creating duplicate codes.

Worked response 4 · HTTP 404 · Series not found

Input · payload.json:

{
  "url": "https://example.com/item/unknown",
  "series_id": 999999
}

Captured SDK response:

{
  "success": false,
  "error": "Series not found"
}

HTTP 404. Discover the exact record id or slug in the same workspace before retrying.

Worked response 5 · HTTP 201

Input · payload.json:

{
  "slug": "premium-fixture",
  "url": "https://example.com/item/premium",
  "tier": "premium",
  "max_usage": 10,
  "valid_from": "2020-01-01",
  "valid_to": "2020-12-31",
  "design": {
    "source": "custom",
    "foreground": "#112233",
    "background": "#ffffff",
    "moduleStyle": "rounded",
    "finderStyle": "circle"
  }
}

Captured SDK response:

{
  "success": true,
  "data": {
    "slug": "premium-fixture",
    "url": "https://example.com/item/premium",
    "tier": "premium",
    "user_id": "user_quro_fixture",
    "organization_id": "org_quro_fixture",
    "workspace_id": "ws_quro_fixture",
    "created_at": "2026-10-06T11:16:13.017Z",
    "series_id": null,
    "name": null,
    "status_id": 1,
    "category_id": 1,
    "design_version": 1,
    "max_usage": 10,
    "valid_from": "2020-01-01",
    "valid_to": "2020-12-31",
    "id": 14,
    "design": {
      "version": 1,
      "source": "custom",
      "foreground": "#112233",
      "background": "#ffffff",
      "moduleStyle": "rounded",
      "finderStyle": "circle",
      "brand": null
    },
    "delivery_mode": "redirect",
    "supports_publishing_state": true,
    "supports_tier_selection": true,
    "management_model": "premium"
  },
  "tier": "premium"
}

Worked response 6 · HTTP 201

Input · payload.json:

{
  "slug": "basic-fixture",
  "url": "https://example.com/item/basic",
  "tier": "basic",
  "name": "Original basic"
}

Captured SDK response:

{
  "success": true,
  "data": {
    "slug": "basic-fixture",
    "url": "https://example.com/item/basic",
    "tier": "basic",
    "user_id": "user_quro_fixture",
    "organization_id": "org_quro_fixture",
    "workspace_id": "ws_quro_fixture",
    "created_at": "2026-10-06T11:16:13.109Z",
    "series_id": null,
    "name": "Original basic",
    "status_id": 1,
    "category_id": 1,
    "design_version": 1,
    "id": 15,
    "design": {
      "version": 1,
      "source": "plain",
      "foreground": "#000000",
      "background": "#ffffff",
      "moduleStyle": "square",
      "finderStyle": "square",
      "brand": null
    },
    "delivery_mode": "redirect",
    "supports_publishing_state": true,
    "supports_tier_selection": true,
    "management_model": "basic"
  },
  "tier": "basic"
}

Worked response 7 · HTTP 201

Input · payload.json:

{
  "url": "mailto:operator@example.com",
  "slug": "ignored-static-slug",
  "tier": "premium",
  "status_id": 2,
  "max_usage": 5
}

Captured SDK response:

{
  "success": true,
  "data": {
    "slug": "6df2of7g",
    "url": "mailto:operator@example.com",
    "tier": "standard",
    "user_id": "user_quro_fixture",
    "organization_id": "org_quro_fixture",
    "workspace_id": "ws_quro_fixture",
    "created_at": "2026-10-06T11:16:13.167Z",
    "series_id": null,
    "name": null,
    "status_id": 1,
    "category_id": 1,
    "design_version": 1,
    "id": 16,
    "design": {
      "version": 1,
      "source": "plain",
      "foreground": "#000000",
      "background": "#ffffff",
      "moduleStyle": "square",
      "finderStyle": "square",
      "brand": null
    },
    "delivery_mode": "static_payload",
    "supports_publishing_state": false,
    "supports_tier_selection": false,
    "management_model": "managed_static_record"
  },
  "tier": "standard"
}

Verify the result

Read the returned id or slug, compare destination, design and tenant. Check the actual redirect and scan before printing; a stored record or queued notification does not prove propagation or delivery.

Errors and recovery

HTTP 409 · http_error: Read the returned reason and current state. A duplicate slug or non-empty workspace must be reconciled before any retry.
HTTP 500 · http_error: Inspect the handler error and dependencies. A missing published Brand kit currently becomes a generic server failure; do not retry by creating duplicate codes.
HTTP 404 · http_error: Discover the exact record id or slug in the same workspace before retrying.
HTTP 401 · auth_error: Authenticate again in the intended environment and organization.
HTTP 403 · action_permission_required: Inspect the actual refusal. The action permission and the verified workspace access are both required; a caller cannot name an ungranted workspace.

Inspect the original handler body as well as the SDK error code. These are observed local refusals, not an exhaustive provider-failure list.

Recovery boundary

After an uncertain write, discover the exact slug before retrying; creation has no caller idempotency key. Delete only a reviewed code that has not been distributed. A missing Brand kit currently produces a generic HTTP 500, not the previously claimed brand_kit_required refusal.

Get QR code: Reads one code by exact numeric id or slug within the verified workspace, including its design, scan count and series. Exact reads can return soft-deleted records.
List QR codes: Lists non-deleted workspace codes with filters, page metadata, tier counts and scan counts; basic codes remain in the same canonical inventory.
Delete QR code: Soft-deletes a code, sets status_id to inactive and writes a redirect tombstone. The historical D1 record remains, and repeated deletion can still succeed.

Create QR code

Outcome

Before you start

Discover the target

Request

Input fields

Worked examples

Worked response 1 · HTTP 201

Worked response 2 · HTTP 409 · Slug already exists

Worked response 3 · HTTP 500 · Failed to create QURO code

Worked response 4 · HTTP 404 · Series not found

Worked response 5 · HTTP 201

Worked response 6 · HTTP 201

Worked response 7 · HTTP 201

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence