Resolve brand for context

Resolve the first eligible brand for a consumer context.

Outcome

Resolve the first eligible brand for a consumer context.

Before you start

Verify whoami and the pinned credential context, then inspect the exact discovered action before preparing input.
Discover a granted Brand workspace. Pass its resourceType/workspace identifier separately from input; a copied fixture identifier grants no access.
The declared permission is brand:read. The active credential, application scope, resource binding and runtime authority must all authorize the request.

Discover the target

topolo whoami --json
topolo actions get app_topolo_brand.brand_kits.resolve_context --detail --json
topolo resources topolo-brand --json
topolo workspaces list topolo-brand --json

Request

POST /api/brand-kits:resolve-context

Resource context is the selected Brand workspace. CLI/SDK action input includes path identifiers; direct HTTP JSON bodies exclude path parameters. Read the reviewed plan for the exact request.

Input fields

Field	Required	Meaning
`consumerAppId`	Yes	Consumer application identifier, or * for a shared workspace/organization binding. Service callers can act only for their verified allowed service.
`workspaceId`	Conditional/optional	Canonical workspace identifier granted to the caller. Workspace archival requires this to match the selected request workspace.
`resourceType`	Conditional/optional	Contextual consumer resource type, supplied together with resourceId.
`resourceId`	Conditional/optional	Contextual consumer resource identifier, supplied together with resourceType.

Exact published input schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "consumerAppId": {
      "type": "string",
      "minLength": 1,
      "description": "Consumer application identifier, or * for a shared workspace/organization binding. Service callers can act only for their verified allowed service."
    },
    "workspaceId": {
      "type": "string",
      "minLength": 1,
      "description": "Canonical workspace identifier granted to the caller. Workspace archival requires this to match the selected request workspace."
    },
    "resourceType": {
      "type": "string",
      "minLength": 1,
      "description": "Contextual consumer resource type, supplied together with resourceId."
    },
    "resourceId": {
      "type": "string",
      "minLength": 1,
      "description": "Contextual consumer resource identifier, supplied together with resourceType."
    }
  },
  "required": [
    "consumerAppId"
  ],
  "additionalProperties": false,
  "anyOf": [
    {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "properties": {
        "consumerAppId": {
          "type": "string",
          "minLength": 1,
          "description": "Consumer application identifier, or * for a shared workspace/organization binding. Service callers can act only for their verified allowed service."
        },
        "workspaceId": {
          "type": "string",
          "minLength": 1,
          "description": "Canonical workspace identifier granted to the caller. Workspace archival requires this to match the selected request workspace."
        },
        "resourceType": {
          "type": "string",
          "minLength": 1,
          "description": "Contextual consumer resource type, supplied together with resourceId."
        },
        "resourceId": {
          "type": "string",
          "minLength": 1,
          "description": "Contextual consumer resource identifier, supplied together with resourceType."
        }
      },
      "required": [
        "consumerAppId",
        "resourceType",
        "resourceId"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "consumerAppId": {
          "type": "string",
          "minLength": 1,
          "description": "Consumer application identifier, or * for a shared workspace/organization binding. Service callers can act only for their verified allowed service."
        },
        "workspaceId": {
          "type": "string",
          "minLength": 1,
          "description": "Canonical workspace identifier granted to the caller. Workspace archival requires this to match the selected request workspace."
        }
      },
      "required": [
        "consumerAppId"
      ],
      "additionalProperties": false
    }
  ]
}

Effects

Reads candidates in order: resource, app + workspace, app, workspace, organization. Skips retired and unpublished kits. Organization identity comes from the verified caller, never input.

Interpret the response

resolved contains the winning scope and non-null binding, published version, absolute assets, publicAssetUrls and presentation. resourceType/resourceId must be paired. The input workspace selects a resolution candidate, while the request resource context controls which Brand workspace the caller may access.

Response identifier contract:

{
  "kind": "brand_kit",
  "identifierSource": "response",
  "idPath": "$.resolved.kit.id"
}

Worked examples

These complete synthetic responses were captured from the local worker over canonical SQL migrations. Auth and R2 dependencies are simulated; notification delivery is not exercised. Set BRAND_WORKSPACE_ID from granted workspace discovery. Save reviewed input as payload.json, validate and inspect the unchanged plan. The final mutation command and MCP confirm flag assume the intended effect has already been authorized.

Minimal example

Input · payload.json:

{
  "consumerAppId": "app_topolo_books",
  "workspaceId": "ws_brand_documentation_fixture"
}

CLI:

topolo actions validate app_topolo_brand.brand_kits.resolve_context --data @payload.json --json
topolo actions plan app_topolo_brand.brand_kits.resolve_context --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_brand.brand_kits.resolve_context --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_brand.brand_kits.resolve_context",
    "input": {
      "consumerAppId": "app_topolo_books",
      "workspaceId": "ws_brand_documentation_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "resolved": {
    "kit": {
      "id": "brand_c794be50-0306-4933-8de8-5609340bed9e",
      "organizationId": "org_documentation_fixture",
      "name": "Reviewed fixture identity",
      "slug": "fixture-minimal",
      "description": "",
      "status": "active",
      "createdAt": "2026-10-03T11:23:59.056Z",
      "updatedAt": "2026-10-03T11:23:59.062Z",
      "currentVersionId": "brand_version_5d0eb310-87f0-4a81-9f27-11240da457e6"
    },
    "version": {
      "id": "brand_version_5d0eb310-87f0-4a81-9f27-11240da457e6",
      "brandKitId": "brand_c794be50-0306-4933-8de8-5609340bed9e",
      "version": 1,
      "status": "published",
      "snapshot": {
        "identity": {
          "displayName": "Fixture identity",
          "shortDescription": "The next generation of software.",
          "domains": [
            "topolo.io"
          ],
          "locales": [
            "en"
          ]
        },
        "visual": {
          "logos": {
            "primaryAssetId": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b"
          },
          "palette": {
            "primary": "#111827",
            "secondary": "#E5E7EB",
            "accent": "#F97316",
            "background": "#FFFFFF",
            "foreground": "#111827",
            "semantic": {}
          },
          "typography": {
            "heading": {
              "family": "Inter",
              "weights": [
                700
              ],
              "fallback": [
                "sans-serif"
              ]
            },
            "body": {
              "family": "Inter",
              "weights": [
                400,
                600
              ],
              "fallback": [
                "sans-serif"
              ]
            }
          },
          "layout": {
            "radius": 16,
            "spacingScale": [
              4,
              8,
              16
            ],
            "logoPlacement": "top-left"
          },
          "imagery": {
            "direction": "Bold, graphic, product-led.",
            "avoid": [
              "generic stock photography"
            ]
          }
        },
        "verbal": {
          "positioning": "Enterprise-grade software without enterprise-era waste.",
          "audiences": [
            "small businesses"
          ],
          "valuePropositions": [
            "One connected software ecosystem"
          ],
          "tone": [
            "bold",
            "direct"
          ],
          "do": [
            "Use specific proof"
          ],
          "dont": [
            "Use unsupported superlatives"
          ],
          "bannedTerms": [
            "guaranteed riches"
          ]
        },
        "claims": [],
        "ctas": [],
        "assets": [
          {
            "id": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b",
            "kind": "logo",
            "name": "Fixture logo",
            "url": "https://brand.example.invalid/api/brand-assets/brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b/content",
            "mimeType": "image/svg+xml"
          }
        ],
        "accessibility": {
          "minimumContrast": 4.5,
          "requireAltText": true,
          "reducedMotion": true
        },
        "legal": {
          "requiredDisclosures": [],
          "prohibitedTopics": []
        }
      },
      "changeNote": "Ready for review",
      "createdAt": "2026-10-03T11:23:59.072Z",
      "updatedAt": "2026-10-03T11:23:59.081Z",
      "publishedAt": "2026-10-03T11:23:59.081Z"
    },
    "binding": {
      "id": "brand_binding_a4ab1e79-6dbe-45c4-af96-093a041abde6",
      "consumerAppId": "app_topolo_books",
      "externalResourceType": "workspace",
      "externalResourceId": "ws_brand_documentation_fixture",
      "brandKitId": "brand_c794be50-0306-4933-8de8-5609340bed9e",
      "createdAt": "2026-10-03T11:23:59.082Z",
      "updatedAt": "2026-10-03T11:23:59.082Z"
    },
    "scope": "app_workspace",
    "publicAssetUrls": {
      "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b": "https://brand.example.invalid/api/public/brand-versions/brand_version_5d0eb310-87f0-4a81-9f27-11240da457e6/assets/brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b"
    },
    "presentation": {
      "schemaVersion": "topolo.brand.presentation/v1",
      "kitId": "brand_c794be50-0306-4933-8de8-5609340bed9e",
      "versionId": "brand_version_5d0eb310-87f0-4a81-9f27-11240da457e6",
      "version": 1,
      "status": "published",
      "publishedAt": "2026-10-03T11:23:59.081Z",
      "name": "Fixture identity",
      "legalName": null,
      "logo": {
        "assetId": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b",
        "url": "https://brand.example.invalid/api/brand-assets/brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b/content",
        "publicUrl": "https://brand.example.invalid/api/public/brand-versions/brand_version_5d0eb310-87f0-4a81-9f27-11240da457e6/assets/brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b",
        "alt": "Fixture identity",
        "mimeType": "image/svg+xml"
      },
      "emailLogo": null,
      "logos": {
        "primary": {
          "assetId": "brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b",
          "url": "https://brand.example.invalid/api/brand-assets/brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b/content",
          "publicUrl": "https://brand.example.invalid/api/public/brand-versions/brand_version_5d0eb310-87f0-4a81-9f27-11240da457e6/assets/brand_asset_dd192c95-76da-4c2e-a61c-8b164686806b",
          "alt": "Fixture identity",
          "mimeType": "image/svg+xml"
        },
        "reversed": null,
        "mark": null,
        "markReversed": null,
        "lockup": null
      },
      "colors": {
        "light": {
          "primary": "#111827",
          "secondary": "#E5E7EB",
          "accent": "#F97316",
          "background": "#FFFFFF",
          "text": "#111827"
        },
        "dark": null
      },
      "typography": {
        "heading": {
          "family": "Inter",
          "weights": [
            700
          ],
          "fallback": [
            "sans-serif"
          ]
        },
        "body": {
          "family": "Inter",
          "weights": [
            400,
            600
          ],
          "fallback": [
            "sans-serif"
          ]
        }
      },
      "layout": {
        "radius": 16
      },
      "email": {
        "senderDisplayName": null,
        "replyToAddress": null,
        "supportAddress": null,
        "footerText": null,
        "unsubscribeText": null
      },
      "legal": {
        "entityName": null,
        "postalAddress": null,
        "companyNumber": null
      }
    }
  }
}

Workflow example

Input · payload.json:

{
  "consumerAppId": "app_topolo_books",
  "workspaceId": "ws_brand_documentation_fixture"
}

CLI:

topolo actions validate app_topolo_brand.brand_kits.resolve_context --data @payload.json --json
topolo actions plan app_topolo_brand.brand_kits.resolve_context --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_brand.brand_kits.resolve_context --resource-type workspace --resource-id "$BRAND_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_brand.brand_kits.resolve_context",
    "input": {
      "consumerAppId": "app_topolo_books",
      "workspaceId": "ws_brand_documentation_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "resolved": {
    "kit": {
      "id": "brand_55886012-13a4-4e95-ad31-3fe2b52cdf20",
      "organizationId": "org_documentation_fixture",
      "name": "Reviewed fixture identity",
      "slug": "fixture-workflow",
      "description": "A governed example identity",
      "status": "active",
      "createdAt": "2026-10-03T11:23:59.104Z",
      "updatedAt": "2026-10-03T11:23:59.105Z",
      "currentVersionId": "brand_version_d00e1d23-0626-418b-ba5c-e9c02b746293"
    },
    "version": {
      "id": "brand_version_d00e1d23-0626-418b-ba5c-e9c02b746293",
      "brandKitId": "brand_55886012-13a4-4e95-ad31-3fe2b52cdf20",
      "version": 1,
      "status": "published",
      "snapshot": {
        "identity": {
          "displayName": "Fixture identity",
          "shortDescription": "The next generation of software.",
          "domains": [
            "topolo.io"
          ],
          "locales": [
            "en"
          ]
        },
        "visual": {
          "logos": {
            "primaryAssetId": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55"
          },
          "palette": {
            "primary": "#111827",
            "secondary": "#E5E7EB",
            "accent": "#F97316",
            "background": "#FFFFFF",
            "foreground": "#111827",
            "semantic": {}
          },
          "typography": {
            "heading": {
              "family": "Inter",
              "weights": [
                700
              ],
              "fallback": [
                "sans-serif"
              ]
            },
            "body": {
              "family": "Inter",
              "weights": [
                400,
                600
              ],
              "fallback": [
                "sans-serif"
              ]
            }
          },
          "layout": {
            "radius": 16,
            "spacingScale": [
              4,
              8,
              16
            ],
            "logoPlacement": "top-left"
          },
          "imagery": {
            "direction": "Bold, graphic, product-led.",
            "avoid": [
              "generic stock photography"
            ]
          }
        },
        "verbal": {
          "positioning": "Enterprise-grade software without enterprise-era waste.",
          "audiences": [
            "small businesses"
          ],
          "valuePropositions": [
            "One connected software ecosystem"
          ],
          "tone": [
            "bold",
            "direct"
          ],
          "do": [
            "Use specific proof"
          ],
          "dont": [
            "Use unsupported superlatives"
          ],
          "bannedTerms": [
            "guaranteed riches"
          ]
        },
        "claims": [],
        "ctas": [],
        "assets": [
          {
            "id": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55",
            "kind": "logo",
            "name": "Fixture logo",
            "url": "https://brand.example.invalid/api/brand-assets/brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55/content",
            "mimeType": "image/svg+xml"
          },
          {
            "id": "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
            "kind": "logo",
            "name": "Fixture email logo",
            "url": "https://brand.example.invalid/api/brand-assets/brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9/content",
            "mimeType": "image/png",
            "altText": "Fixture email identity"
          }
        ],
        "accessibility": {
          "minimumContrast": 4.5,
          "requireAltText": true,
          "reducedMotion": true
        },
        "legal": {
          "requiredDisclosures": [],
          "prohibitedTopics": []
        },
        "communications": {
          "emailLogoAssetId": "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
          "senderDisplayName": "Fixture identity",
          "replyToAddress": "reply@example.invalid",
          "supportAddress": "support@example.invalid",
          "legalFooter": {
            "entityName": "Fixture identity Ltd",
            "registeredAddress": "1 Fixture Street, Example City",
            "companyNumber": "FIXTURE-001"
          },
          "unsubscribeText": "Manage your message preferences.",
          "footerText": "Synthetic documentation example."
        }
      },
      "changeNote": "Ready for review",
      "createdAt": "2026-10-03T11:23:59.115Z",
      "updatedAt": "2026-10-03T11:23:59.118Z",
      "publishedAt": "2026-10-03T11:23:59.118Z"
    },
    "binding": {
      "id": "brand_binding_813652d7-03ee-4cb3-b08c-001b1ba912f1",
      "consumerAppId": "app_topolo_books",
      "externalResourceType": "workspace",
      "externalResourceId": "ws_brand_documentation_fixture",
      "brandKitId": "brand_55886012-13a4-4e95-ad31-3fe2b52cdf20",
      "createdAt": "2026-10-03T11:23:59.119Z",
      "updatedAt": "2026-10-03T11:23:59.119Z"
    },
    "scope": "app_workspace",
    "publicAssetUrls": {
      "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55": "https://brand.example.invalid/api/public/brand-versions/brand_version_d00e1d23-0626-418b-ba5c-e9c02b746293/assets/brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55",
      "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9": "https://brand.example.invalid/api/public/brand-versions/brand_version_d00e1d23-0626-418b-ba5c-e9c02b746293/assets/brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9"
    },
    "presentation": {
      "schemaVersion": "topolo.brand.presentation/v1",
      "kitId": "brand_55886012-13a4-4e95-ad31-3fe2b52cdf20",
      "versionId": "brand_version_d00e1d23-0626-418b-ba5c-e9c02b746293",
      "version": 1,
      "status": "published",
      "publishedAt": "2026-10-03T11:23:59.118Z",
      "name": "Fixture identity",
      "legalName": null,
      "logo": {
        "assetId": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55",
        "url": "https://brand.example.invalid/api/brand-assets/brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55/content",
        "publicUrl": "https://brand.example.invalid/api/public/brand-versions/brand_version_d00e1d23-0626-418b-ba5c-e9c02b746293/assets/brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55",
        "alt": "Fixture identity",
        "mimeType": "image/svg+xml"
      },
      "emailLogo": {
        "assetId": "brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
        "url": "https://brand.example.invalid/api/brand-assets/brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9/content",
        "publicUrl": "https://brand.example.invalid/api/public/brand-versions/brand_version_d00e1d23-0626-418b-ba5c-e9c02b746293/assets/brand_asset_dce3c24f-65dd-4579-913f-9ffbf74619c9",
        "alt": "Fixture email identity",
        "mimeType": "image/png"
      },
      "logos": {
        "primary": {
          "assetId": "brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55",
          "url": "https://brand.example.invalid/api/brand-assets/brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55/content",
          "publicUrl": "https://brand.example.invalid/api/public/brand-versions/brand_version_d00e1d23-0626-418b-ba5c-e9c02b746293/assets/brand_asset_87bffee4-7249-419b-b4c1-8edeeb732d55",
          "alt": "Fixture identity",
          "mimeType": "image/svg+xml"
        },
        "reversed": null,
        "mark": null,
        "markReversed": null,
        "lockup": null
      },
      "colors": {
        "light": {
          "primary": "#111827",
          "secondary": "#E5E7EB",
          "accent": "#F97316",
          "background": "#FFFFFF",
          "text": "#111827"
        },
        "dark": null
      },
      "typography": {
        "heading": {
          "family": "Inter",
          "weights": [
            700
          ],
          "fallback": [
            "sans-serif"
          ]
        },
        "body": {
          "family": "Inter",
          "weights": [
            400,
            600
          ],
          "fallback": [
            "sans-serif"
          ]
        }
      },
      "layout": {
        "radius": 16
      },
      "email": {
        "senderDisplayName": "Fixture identity",
        "replyToAddress": "reply@example.invalid",
        "supportAddress": "support@example.invalid",
        "footerText": "Synthetic documentation example.",
        "unsubscribeText": "Manage your message preferences."
      },
      "legal": {
        "entityName": "Fixture identity Ltd",
        "postalAddress": "1 Fixture Street, Example City",
        "companyNumber": "FIXTURE-001"
      }
    }
  }
}

Verify the result

Check winning scope, tuple, kit and exact version against the intended consumer context. No match is a refusal; do not silently substitute an unrelated identity.

Errors and recovery

refused · HTTP 400

{
  "input": {
    "consumerAppId": "app_topolo_books",
    "resourceType": "workspace"
  },
  "response": {
    "error": "invalid_input",
    "details": [
      {
        "path": [],
        "code": "custom"
      }
    ]
  }
}

auth_error (HTTP 401): CLI/SDK authentication classification when Auth returns a non-code message: restore the authorized credential, then verify whoami and context. Preserve the exact service message.
permission_denied (HTTP 403): Use the exact permission and granted resource required by the reviewed action; organization membership alone is insufficient.
workspace_required (HTTP 400): Discover and select a granted Brand workspace before preparing the request.
brand_storage_unavailable (HTTP 503): The Brand storage bindings are unavailable. Preserve the request identifier and report the service fault; do not retry an unverified mutation.
invalid_input (HTTP 400): Correct the reported fields, validate the complete payload and review the resulting plan before retrying.

Recovery boundary

This read or validation does not change Brand service state.

app_topolo_brand.brand_bindings.list: List consumer bindings for kits in the selected workspace.
app_topolo_brand.brand_kit_versions.get: Read an exact Brand version and its rendering presentation.

Evidence

Four real local SQLite stores use all canonical migrations; Auth identity/grants and archival plus R2 object storage are explicitly simulated. Notifications are disabled in fixtures. No notification delivery, live mutation, gateway credential parity or deployed environment proof is claimed. Fixture identifiers and timestamps are synthetic and must be replaced by exact authorized resource discovery.

Documentation history

2026-10-18

Aligned the precise response schema with reviewed Brand source, including the rendering presentation fields for logos, typography and layout.
Corrected 2 captured response examples to include the complete presentation; request inputs and the other guidance are unchanged.
Reviewed source revision a4b22b76664478536809b7a438232645661175b6 and retained 2 request/response captures from the documented fixture lineage. Auth/workspace grants and object storage remain simulated; notifications were disabled. No new test execution or deployed environment validation is established.
This entry records a documentation correction; product release version, release date and runtime adoption are not inferred.