Generate series QR codes

Generates 1–1000 codes using a naming/URL pattern. HTTP 200 can contain partial failures; codes is a preview of at most ten, and error_messages is at most five.

Outcome

Generates 1–1000 codes using a naming/URL pattern. HTTP 200 can contain partial failures; codes is a preview of at most ten, and error_messages is at most five.

Before you start

Verify identity, environment and the intended organization before discovery.
Discover the published series: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.series.generate --detail --json

id: Exact returned series or export id converted to a string. Discover series through series.list; retain export ids from exports.create.
categoryId: Discovered category id used by a code filter or series generation.
statusId: Discovered code status id for generation or filtering.

Request

POST /series/{id}/generate

Inspect parameters and test this action.

Input fields

Field	Required	Meaning
`id`	Yes	Exact returned series or export id converted to a string. Discover series through series.list; retain export ids from exports.create.
`count`	No	Number of codes to generate, from 1 to 1000. Inspect generated/total/errors even with HTTP 200.
`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.
`namePattern`	No	Generation name pattern supporting {number}, {padded} and {series}. Collisions receive suffixes and can ultimately produce partial failures.
`urlPattern`	No	Generation destination pattern supporting {number}, {padded} and {series}. Do not assume a {slug} substitution; it is not implemented by this handler.
`categoryId`	No	Discovered category id used by a code filter or series generation.
`statusId`	No	Discovered code status id for generation or filtering.
`startNumber`	No	First non-negative sequence number used by generation; rerunning a sequence can produce additional suffixed codes.
`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.series.generate --data @payload.json --json
topolo actions plan app_topolo_quro.series.generate --resource-type workspace --resource-id "$WORKSPACE_ID" --data @payload.json --confirm --json
topolo actions call app_topolo_quro.series.generate --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.series.generate",
    "input": {
      "id": "1",
      "count": 2,
      "tier": "basic",
      "namePattern": "Fixture {padded}",
      "urlPattern": "https://example.com/item/{number}"
    },
    "resourceType": "workspace",
    "resourceId": "ws_quro_fixture",
    "confirm": true
  }
}

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_quro.series.generate",
    "input": {
      "id": "1",
      "count": 2,
      "tier": "basic",
      "namePattern": "Fixture {padded}",
      "urlPattern": "https://example.com/item/{number}"
    },
    "resourceType": "workspace",
    "resourceId": "ws_quro_fixture",
    "confirm": true,
    "detail": true
  }
}

Worked response 1 · HTTP 200

Input · payload.json:

{
  "id": "1",
  "count": 2,
  "tier": "basic",
  "namePattern": "Fixture {padded}",
  "urlPattern": "https://example.com/item/{number}"
}

Captured SDK response:

{
  "success": true,
  "data": {
    "generated": 2,
    "total": 2,
    "errors": 0,
    "codes": [
      {
        "slug": "fixture-001",
        "name": "Fixture 001",
        "url": "https://example.com/item/1",
        "tier": "basic",
        "redirect_url": "https://ol0.me/fixture-001"
      },
      {
        "slug": "fixture-002",
        "name": "Fixture 002",
        "url": "https://example.com/item/2",
        "tier": "basic",
        "redirect_url": "https://ol0.me/fixture-002"
      }
    ],
    "error_messages": []
  }
}

HTTP 200. Check generated, total and errors independently of HTTP status. Discover every created code through paginated qurocodes.list filtered by seriesId. The preview is not the full generated inventory.

Worked response 2 · HTTP 200 · Partial generation

Input · payload.json:

{
  "id": "1",
  "count": 12,
  "tier": "standard",
  "namePattern": "Fixture collision",
  "urlPattern": "https://example.com/collision/{number}"
}

Captured SDK response:

{
  "success": true,
  "data": {
    "generated": 10,
    "total": 12,
    "errors": 2,
    "codes": [
      {
        "slug": "fixture-collision",
        "name": "Fixture collision",
        "url": "https://example.com/collision/1",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision"
      },
      {
        "slug": "fixture-collision-1",
        "name": "Fixture collision",
        "url": "https://example.com/collision/2",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision-1"
      },
      {
        "slug": "fixture-collision-2",
        "name": "Fixture collision",
        "url": "https://example.com/collision/3",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision-2"
      },
      {
        "slug": "fixture-collision-3",
        "name": "Fixture collision",
        "url": "https://example.com/collision/4",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision-3"
      },
      {
        "slug": "fixture-collision-4",
        "name": "Fixture collision",
        "url": "https://example.com/collision/5",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision-4"
      },
      {
        "slug": "fixture-collision-5",
        "name": "Fixture collision",
        "url": "https://example.com/collision/6",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision-5"
      },
      {
        "slug": "fixture-collision-6",
        "name": "Fixture collision",
        "url": "https://example.com/collision/7",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision-6"
      },
      {
        "slug": "fixture-collision-7",
        "name": "Fixture collision",
        "url": "https://example.com/collision/8",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision-7"
      },
      {
        "slug": "fixture-collision-8",
        "name": "Fixture collision",
        "url": "https://example.com/collision/9",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision-8"
      },
      {
        "slug": "fixture-collision-9",
        "name": "Fixture collision",
        "url": "https://example.com/collision/10",
        "tier": "standard",
        "redirect_url": "https://ol0.me/fixture-collision-9"
      }
    ],
    "error_messages": [
      "Failed to generate unique slug for Fixture collision",
      "Failed to generate unique slug for Fixture collision"
    ]
  }
}

Worked response 3 · HTTP 404 · Series not found

Input · payload.json:

{
  "id": "999999",
  "count": 1
}

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 4 · HTTP 400 · Invalid series ID

Input · payload.json:

{
  "id": "not-numeric"
}

Captured SDK response:

{
  "success": false,
  "error": "Invalid series ID"
}

HTTP 400. Correct the reviewed payload using inputSchema and the returned handler message.

Verify the result

Check generated, total and errors independently of HTTP status. Discover every created code through paginated qurocodes.list filtered by seriesId. The preview is not the full generated inventory.

Errors and recovery

HTTP 404 · http_error: Discover the exact record id or slug in the same workspace before retrying.
HTTP 400 · http_error: Correct the reviewed payload using inputSchema and the returned handler message.
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

Never blindly repeat an uncertain or partial generation: retries can create more codes with suffixed slugs. Reconcile the series inventory and approve only the missing work. Compensating deletions require reviewing printed/distributed codes.

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.
List series generation patterns: Returns base and template-specific naming and URL patterns for an existing series within its verified tenant.

Generate series QR codes

Outcome

Before you start

Discover the target

Request

Input fields

Worked examples

Worked response 1 · HTTP 200

Worked response 2 · HTTP 200 · Partial generation

Worked response 3 · HTTP 404 · Series not found

Worked response 4 · HTTP 400 · Invalid series ID

Verify the result

Errors and recovery

Recovery boundary

Related actions

Evidence