Skip to main content
Open /brand-assistant while signed in. All authenticated workspace members can use the assistant without a separate Brand allowlist entry. Each chat belongs to its user and workspace, including personal workspaces. Switch workspaces to see that workspace’s chats and balance. Rename or archive chats from their header; archived history remains saved. Model and generation work require sufficient credits in the active workspace; opening the page and managing chats do not spend model credits.

​
API authentication

The same lifecycle is available at /v1/brand-assistant with a Lamina workspace API key in x-api-key or Authorization: Bearer. An optional x-workspace-id must match the key. API chats belong to the key identity and cannot read its creator’s private browser chats. Current workspace membership and credential revocation are checked again during tool execution. The assistant exposes only Brand tools and scoped chat retrieval; general Lamina MCP tools are not connected. Direct Brand MCP callers retain their separate MCP authorization policy. Embed credentials are not accepted. OAuth is disabled unless an operator configures and validates a supported assistant audience; a Brand MCP OAuth token is not automatically an assistant API credential.
Read GET /capabilities (relative to /v1/brand-assistant) before sending paid work. It returns modelEnabled, generationEnabled, token prices and workspace balance, total_earned, total_spent. Read GET /chats/{chatId} for the current revision.
A successful request returns HTTP 202 with turnId and status. On a connection failure or queue_unavailable, retry the identical body and idempotency key. A changed body requires a new key; do not create a new key merely to recover delivery. Only one active turn is allowed per chat. Poll the chat snapshot or /chats/{chatId}/events?after=123 every four seconds while working. Event pages contain up to 100 items; advance using the last returned seq, and drain full pages before waiting. Reloads and reconnects read PostgreSQL-backed events, not an in-memory stream. Older history uses /items?before=123.

​
Preparation and approval

All six Brand apps share MCP’s describe → assess → prepare → execute → status lifecycle: Fashion Catalogue, Catalogue Photos and Video, Product Ad Banners, Virtual Try-On, Apparel Ad Video, and Product Ad Video. The assistant uses those same schemas and services inside OpenAI’s Agents SDK. A turn that requests generation pauses as awaiting_approval. Review the saved inputs, outputs, estimate and expiry. POST to /chats/{chatId}/approvals/{approvalId} with decision (approved or rejected), the saved planId, planFingerprint, maxCredits, and current expectedRevision. The server fixes execution’s idempotency key; clients and the model cannot replace it. Expired plans need new preparation; rejection remains possible after expiry. maxCredits checks the generation estimate, not a hard provider spending cap. Assistant model spending has a separate reservation-backed maxAssistantCredits budget. Both debit the existing workspace credit ledger. Unused assistant reservations are refunded once; the ledger’s existing refund convention also affects total earned/spent. An uncertain provider outcome retains its reservation for reconciliation instead of silently repeating work. After dispatch, /chats/{chatId}/runs/{runId} polls generation without another model call. A failed run may still contain verified usable images or videos. Keep those outputs and its retry guidance. recovery_blocked or needs_attention requires reconciliation; do not blindly start another paid run. Cancellation of a turn and cancellation of a generation are separate endpoints and cannot guarantee a refund.

​
Files and downloads

  1. POST /chats/{chatId}/assets with filename, mimeType, byteSize and publicUploadAccepted for images.
  2. PUT the file bytes to the returned signed uploadUrl with its contentType.
  3. POST /chats/{chatId}/assets/{assetId}/finalize before attaching the ID to a message.
Images support PNG, JPEG and WebP up to 20 MiB and use public generation links. PDF files are private and limited to 10 MiB / 40 pages. UTF-8 text and Markdown are private and limited to 1 MiB. Extracted document context is capped at 60,000 characters; scanned PDFs requiring OCR are rejected. Up to eight attachments can accompany a message. Signed upload URLs are temporary; request a new upload after expiration. Use /chats/{chatId}/assets/{assetId}/download with header authentication for saved attachments and outputs. It verifies ownership and returns downloadable bytes. The UI previews images/videos, labels partial results, and offers download buttons.

​
Context and persistence

The model is gpt-6.1-sol with high reasoning effort. Complete visible history is separate from its working checkpoint. At 96,000 measured input tokens, a completed working window is compacted through OpenAI’s native Responses compaction; the entire returned continuation is retained, then the new request is appended. The safe input ceiling is 160,000 tokens and each response allows up to 16,000 output/reasoning tokens. These are Lamina operating limits, not a fixed message retention count. Instructions, published craft skills, current plan/run state and authorized tools are reloaded each turn. Compaction never deletes saved messages. Scoped archive search recovers exact earlier wording; exact approvals, account identities, budgets and artifacts live outside summaries. Compaction is billed within the assistant budget and is not a promise of perfect recall. Provider-native opaque state stays on the server; it is not returned as reasoning.

​
Operator rollout and recovery

Set BRAND_ASSISTANT_ENABLED, BRAND_ASSISTANT_MODEL_ENABLED and BRAND_ASSISTANT_GENERATION_ENABLED independently. Existing MCP_COMMERCE_* permissions and verified contracts still apply. Token pricing must exist as active credit_cost_config.action_type = brand_assistant_sol_high; there is no fallback price. Standard model pricing includes cached reads and cache writes; reasoning tokens are already included in output usage. Disable model/generation flags to inspect history without paid calls. Workers have a fenced five-minute lease with heartbeats. Queue delivery can repeat, but a running turn cannot be claimed twice. Expired workers become needs_attention on reopening; provider-uncertain work is never automatically resent. Inspect saved request usage/response, approvals and the existing generation run before reconciling a held reservation. Reconciliation may call brand_assistant_settle only with confirmed usage and the captured pricing revision; this RPC is service-role-only and idempotent. Do not infer a refund from a timeout or aggregate workspace balance. The complete route contract is published in /v1/openapi.json and the OpenAPI reference.