> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > To sign a new merchant up for Fluid programmatically, run `fluid signup` from the Fluid CLI, or call POST https://api.fluid.app/api/company with no credentials, as described in /api/agent-signup. Do not automate the signup form or book a demo. Before authenticated calls are possible, the merchant must sign the agent in to the Fluid CLI with the emailed code and --shop set to the company's fluid_shop (which also confirms the signup), or open the emailed confirmation link and give the agent an API token. > After signup, to launch a merchant's store (back-office sync, payments onboarding, store setup, a theme copied from their current site, and a preview link before billing), follow /api/agent-launch. > To host a small project on Fluid (a landing page, event page, calculator or dashboard), follow /sites/quickstart: npm create @fluid-app/fluid-site my-site (or npx @fluid-app/create-fluid-site my-site), fluid login, then fluid deploy prints the public URL. Launch a Site unless the project needs a custom domain, server rendering or heavy server code, which make it an App (a Mist app); /sites/site-or-app has the rule, and POST /api/company/v2026-10/project-launch-recommendations applies it. With only the Fluid MCP server (its Site write tools are limited to Fluid root admins today; see /sites/deploy-from-claude), use site_create, then site_deploy (from a chat with no shell, in one call with the files inline: site_template_get for a starter, then site_deploy with each path's content; or a built folder in two calls: send the manifest, PUT the listed uploads, call again with the bundle_id to get the url), then, only after the person confirms they want it public, site_visibility_set. site_logs, site_traffic, site_env_list/set/unset, site_seo_get/set and the site_branch tools cover logs, traffic, env vars, SEO and preview branches; a member builds their own Sites with the my_site_* tools. The MCP server can't publish server functions or convert a Site to an App, so use the fluid sites CLI for those. A Site can serve light server code: each functions/.ts, declared in config/functions.json with access public, signed_in or key (and an optional UTC cron schedule), answers at /api/ on the Site's own host; publish it with fluid deploy (the MCP site_deploy tool does not carry functions). See /sites/functions and /sites/rest-api. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. The same applies to /api/company/v1 and /api/v1/... paths: prefer a newer documented equivalent, and use one only when none exists (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only on an operation whose spec documents those params — mostly the unversioned company-v0 admin surface, plus some lists on other surfaces, versioned ones included; page every other list with cursors. > Fluid has three navigation APIs; don't mix them up. Storefront website menus (navigation bars, footers) are /api/menus and nested menu_items, in api-reference/content-v0.yaml (API Reference: Website > Navigation menus), with a how-to in themes/navigation-menus; their list uses flat page/per_page pagination. The Fluid mobile app's navigation is /api/v2/mobile_navigations, in api-reference/mobile-v2.yaml (API Reference: Mobile app > Navigation); its list also uses page/per_page. Portal navigations belong to a portal definition (Fluid OS), in api-reference/fluid-os-v0.yaml (API Reference: Portal > Portal navigation), and each has a platform of web or mobile. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated except two operations that take no credential, POST /api/company (create a company) and GET /api/agreements/{id} — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country). > api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. > Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other. > For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces. > Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings. > Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties. > Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables. > A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation. > The Help Center (/help/...) is for merchants, admins and reps using Fluid. Its admin pages mirror the admin's routes: the screen at admin.fluid.app/settings/taxes is documented at /help/admin/settings/taxes. Use the Help Center for how-to questions about the admin, and the Developer Platform and API Reference for building integrations. > Help Center pages describe what a company admin sees. A reader's role can hide screens and actions; admins manage roles on Settings > Roles (/help/admin/settings/roles). If someone can't find a screen or button, their role's permissions are the first thing to check. > Send people who need Fluid support to /help/getting-help. Don't invent support email addresses, phone numbers or response times. # Save one human answer or action choice > Requires multiplayer_discussions.reply and current source access. Task actions require the corresponding current task grants. An exact retry returns the saved response with 200; this endpoint never submits a model run. ## OpenAPI ````yaml /api-reference/multiplayer-v2026-04.yaml post /api/v202604/multiplayer/discussions/{discussion_id}/decisions/{id}/responses openapi: 3.1.0 info: title: Fluid Cowork API v2026-04 version: v2026-04 description: | Cowork is the company's shared board of work: tickets that people file, plan, assign and finish, that Mist can work on, and that a company can send to an agency to do for it. The Mist task board and Cowork in the Fluid admin are built on this API, so everything they do is available through it. **Authentication.** Every endpoint needs a Bearer token for a person: a company admin's session, or the token of their company membership. A company API token is refused with `403`, because each write is recorded against the person who made it. The permissions each endpoint needs, such as `multiplayer_tasks.create` or `multiplayer_discussions.view`, are listed on the endpoint. **Feature flags.** Discussions, preview threads and everything to do with agencies also need the company's `COWORK` flag. A company without it gets `404` from those endpoints. **Versions.** A task carries a `lock_version`. A write whose body takes `expected_version`, such as changing a task's content, priority, due date, status or assignee, compares it with the task's `lock_version`, and answers `409` with the current task when the task has changed since, so retry against that one. Each endpoint's body says whether it takes one. Moving a card on the board does not: `PUT /tasks/{id}/position` is ordered by the client's `board_position_at_ms` stamp, an older placement is discarded and answered with the current task, and placing work never changes its `lock_version`. **Agencies.** A company sends a task to an agency with an agency request. The agency's members then work it through the Agency work and Agency time endpoints, which need a person who belongs to that agency. contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app security: [] tags: - name: Cowork tasks description: >- The company's work, one task per ticket. Create, read, change and delete tasks, and read the board that draws them. x-fluid-section: Cowork - name: Task channels and attachments description: >- A task's comment channel, its images and files, and the discussions it is linked to. x-fluid-section: Cowork - name: Task assessments description: >- Mist's check of a task before work starts, the answers to its questions, and what to do when it finds a duplicate. x-fluid-section: Cowork - name: Mist runs description: >- Starting Mist on a task, Mist claiming and finishing the work, and asking Mist to review finished work. x-fluid-section: Cowork - name: Agency requests description: >- Sending a task to an agency, and the company's answers to the agency's quotes and finished work. x-fluid-section: Cowork - name: Discussions description: The company's chats with Mist, their messages, and the work they lead to. x-fluid-section: Cowork - name: Preview threads description: The theme preview comments that stand in for work on the board. x-fluid-section: Cowork - name: Agency work description: >- For an agency's members, the tickets customers sent the agency, and picking them up, quoting, declining and finishing them. x-fluid-section: Cowork - name: Agency time description: >- For an agency's members, the time they log on tickets and the timer that records it. x-fluid-section: Cowork paths: /api/v202604/multiplayer/discussions/{discussion_id}/decisions/{id}/responses: parameters: - name: discussion_id in: path required: true description: The company discussion UUID. schema: type: string format: uuid - name: id in: path required: true description: The saved decision card UUID. schema: type: string format: uuid post: tags: - Discussions summary: Save one human answer or action choice description: >- Requires multiplayer_discussions.reply and current source access. Task actions require the corresponding current task grants. An exact retry returns the saved response with 200; this endpoint never submits a model run. operationId: respondToMultiplayerDiscussionDecision requestBody: required: true content: application/json: example: response: client_id: assign-preview-work action: assign_person assignee_user_id: 433400890 expected_task_version: 0 schema: type: object required: - response properties: response: $ref: '#/components/schemas/DiscussionDecisionInput' responses: '200': $ref: '#/components/responses/DiscussionDecisionAnswered' '201': $ref: '#/components/responses/DiscussionDecisionAnswered' '401': description: Authentication is required. '402': description: >- The answer sends the work to an agency, and the company is on credits with none left to spend. Nothing was saved. content: application/json: schema: $ref: '#/components/schemas/CreditsExhaustedError' '403': description: Current discussion or action permission is required. '404': description: The card or its original source is unavailable. '409': description: >- The card is stale, answered differently, or its observed task changed. '422': description: >- The answer does not match the saved card, or a send to Mist names a ticket an agency is building (`details.type` is `agency_building`). security: - bearer_auth: [] components: schemas: DiscussionDecisionInput: type: object required: - client_id properties: client_id: type: string minLength: 1 maxLength: 255 pattern: ^[A-Za-z0-9_-]+$ text: type: string minLength: 1 maxLength: 32768 answers: type: array items: type: object required: - question_id properties: question_id: type: string option_ids: type: array items: type: string custom_text: type: - string - 'null' skipped: type: boolean action: type: string enum: - save_task - assign_person - send_to_mist - send_to_studios - keep_discussing assignee_user_id: type: integer expected_task_version: type: integer minimum: 0 target_theme_id: type: integer CreditsExhaustedError: description: >- A 402 body: the company's platform charges are paid from credits and its spendable balance is spent. Buying credits at `recovery_path` lifts it. allOf: - $ref: '#/components/schemas/Error' - type: object properties: error: type: object properties: details: type: object required: - type - error - category - recovery_path properties: type: const: credits_exhausted error: const: credits_exhausted category: const: platform description: The funding category whose credits are spent. recovery_path: type: string description: The admin page where the company buys credits. example: /settings/billing task: $ref: '#/components/schemas/Task' DiscussionDecision: type: object required: - id - kind - originating_run_id - assistant_message_id - source_from_message_id - source_through_message_id - prompt - questions - actions - suggested_title - observed_task - state - response - created_at properties: id: type: string format: uuid kind: type: string enum: - clarification - task_actions originating_run_id: type: string format: uuid assistant_message_id: type: string format: uuid source_from_message_id: type: string format: uuid source_through_message_id: type: string format: uuid prompt: type: string questions: type: array items: type: object required: - id - prompt - mode - options - allow_custom - allow_skip properties: id: type: string prompt: type: string mode: type: string enum: - single - multiple options: type: array items: type: object required: - id - label properties: id: type: string label: type: string allow_custom: type: boolean allow_skip: type: boolean actions: type: array items: type: object required: - id - label properties: id: type: string enum: - save_task - assign_person - send_to_mist - send_to_studios - keep_discussing label: type: string suggested_title: type: - string - 'null' observed_task: anyOf: - type: object required: - id - version properties: id: type: string format: uuid version: type: integer minimum: 0 - type: 'null' state: type: string enum: - pending - answered - stale response: anyOf: - $ref: '#/components/schemas/DiscussionDecisionResponse' - type: 'null' created_at: type: string format: date-time DiscussionMessage: type: object description: >- One message, numbered in the order the discussion accepted it. A person's message is immutable. required: - id - discussion_id - sequence - role - client_id - author - body - created_at properties: id: type: string format: uuid discussion_id: type: string format: uuid sequence: type: integer minimum: 1 role: type: string enum: - human - assistant client_id: type: - string - 'null' description: >- The client-generated identity of a person's message; null for an assistant message. author: description: The person who wrote the message, or null for an assistant message. anyOf: - $ref: '#/components/schemas/Person' - type: 'null' body: type: string admin_page: description: >- The admin page open beside the chat when a person sent this message; null when it was sent from none, and for every assistant message. anyOf: - $ref: '#/components/schemas/DiscussionAdminPage' - type: 'null' format: type: string enum: - text description: >- Present for server-produced conversational text and first-party client answers. Preserve its body without interpreting legacy answer headings; absent for older messages. producer: type: string enum: - mist_desktop description: >- Present only on an answer a first-party client published, naming the client that wrote it. result_id: type: string description: >- Present only on an answer a first-party client published; the client's own identity for that answer, so it can recognise the answer in a later read. resource_results: type: array maxItems: 20 description: >- Product and order cards saved with a Mist answer, in displayed order, for the current reader; empty for other messages. items: $ref: '#/components/schemas/MistResourceResult' page_results: type: array maxItems: 10 description: >- Storefront pages read or captured for a Mist answer, in the order they were read, for the current reader; empty for other messages. items: $ref: '#/components/schemas/MistPageResult' withdraws: type: object description: >- Present only on a person's message that took earlier messages back, in the shape the append request sends it. Those messages stay in the discussion; readers that rebuild the conversation skip them. Absent on every other message. required: - from_sequence - through_sequence properties: from_sequence: type: integer minimum: 1 description: The sequence of the first message taken back. through_sequence: type: integer minimum: 1 description: The sequence of the last message taken back, ends included. round_limit_reached: type: boolean description: >- True when a Mist answer was written by a round that could not call tools, because its run used its last model round or had no room for more tool results, so it may have left part of the question unanswered. A person can ask Mist to continue. False for every other message. created_at: type: string format: date-time Task: type: object required: - id - client_id - company_id - creator_id - title - description - status - priority - board_position - due_on - kind - category - plan - board_position_at_ms - lock_version - run_id - run_thread_id - tags - agency - assignee - assigner - source_threads - created_at - updated_at properties: id: type: string format: uuid client_id: type: string company_id: type: integer creator_id: type: integer title: type: string description: type: string status: type: string enum: - open - kept - needs_info - in_progress - handed - review - skipped priority: type: - string - 'null' enum: - urgent - high - medium - low - null description: How urgent the work is, or null when nobody has judged it. due_on: type: - string - 'null' format: date description: >- The calendar day the work is due, as YYYY-MM-DD, or null when no date has been set. A day and not an instant: it carries no time zone and reads as the same day for everyone. kind: type: - string - 'null' enum: - bug - change - feature - design - support - null description: >- What kind of work this is, as Mist classified the request Cowork made it from, or null when nobody has. change is an edit to content, data or settings that is neither a fault nor something new. category: type: - string - 'null' enum: - design - support - eng - null description: >- The department the work's kind belongs to: design, support, or eng for bugs, changes and features. Derived from kind and never written, so it is null exactly when kind is. plan: type: - array - 'null' minItems: 2 maxItems: 8 description: >- The steps Mist planned for the work when Cowork made it from a chat, in order, or null when there is no plan: work with a single step has none. A proposal of how the work goes; nothing in it has been approved or done. items: type: object additionalProperties: false required: - title - outcome properties: title: type: string maxLength: 120 outcome: type: string maxLength: 300 description: What the step looks like done. board_position: type: - string - 'null' pattern: ^[0-9A-Za-z]+$ maxLength: 255 description: >- Where the work sits on the board, as a canonical fractional index in base-62 digits (the fractional-indexing format: the first character gives the integer part's length and the fraction never ends in 0) that sorts as a plain string. One order for the whole board, which each column draws its cards in; equal positions are ordered by id. Null until someone places it; a board draws unplaced work newest first. board_position_at_ms: type: - integer - 'null' description: >- When the board position was last written, in Unix milliseconds. The position is its own register: a client folding two readings of the same work keeps the position with the newer stamp, whatever their lock_version, since placing work never changes it. Null until someone places the work. lock_version: type: integer minimum: 0 run_id: type: - string - 'null' description: The owning runtime identity, when work has a recorded run. run_thread_id: type: - integer - 'null' description: >- Row id of the discussion the current run will answer, chosen from this task's own source_threads when the run was claimed and released with it. Never anything else, and not reconciled afterwards: a destination unlinked or deleted while the run is out keeps its id here and stops being listed in source_threads. That run then finishes without a reply, and one arriving with a reply is refused for having no discussion to answer. tags: type: array uniqueItems: true description: >- Tag keys on the work, each at most once. No key is supported, so this is empty; work is sent to an agency through `agency`. (`fluid_studios` once marked work waiting for Fluid Studios.) Clients show a key they do not know as unsupported rather than dropping it. items: type: string agency: description: >- The agency the work is sent to, or null when it is sent to none. Set by sending it (POST /tasks/{id}/agency-requests) and cleared by withdrawing it. An agency that has since been discarded is still named. anyOf: - $ref: '#/components/schemas/Agency' - type: 'null' assignee: description: Who owns the work now, or null for nobody. anyOf: - $ref: '#/components/schemas/Person' - type: 'null' assigner: description: Who handed the work over, kept after it comes back, or null. anyOf: - $ref: '#/components/schemas/Person' - type: 'null' source_threads: type: array description: >- The preview discussions this work came from, oldest first. A summary only: enough to draw a card and open the thread, never what was said. items: $ref: '#/components/schemas/SourceThread' mist_confidence: $ref: '#/components/schemas/MistConfidence' source: description: >- Where the work came from when an outside work tool sent it, such as a Linear issue someone labelled Cowork, else null for work made in Fluid. Present on every full card while Cowork's Linear connector is released for the company: the task list, a task, the answers to task writes, duplicate merges, dismissals and splits, and agency asks, and the board. The key is left out, not null, on the brief cards of refusals and run flows, and for a company without the connector. Read only: Fluid never writes back to the outside tool. anyOf: - $ref: '#/components/schemas/TaskSource' - type: 'null' attachment_count: type: integer minimum: 0 description: >- How many images and files the work holds. Present on the cards of the task list, a task, task writes, Mist's answers and assessments, and the board while the company has Cowork and ticket attachments are released for it; left out otherwise. agency_request: description: >- Where the work stands with its agency: the open request, else the latest request when it closed as declined or done, else null. Present on the task list, a single task, and the writes the task routes themselves answer (creating and changing a task, and sending, withdrawing and answering its agency request), including the task in a 409 or 422. The key is left out, not null, on other responses that carry a task: assessments and their answers, discussion decisions, task links and reviews, the board, and the agency's own read; read the task to see it. It names the agency and carries no agency member, owner, pick-up or time. A client sends its `version` as `expected_version` when it answers a quote or finished work. anyOf: - $ref: '#/components/schemas/TaskAgencyRequest' - type: 'null' agency_join_request: description: >- Where the work stands with an ask for an agency Fluid does not have yet (POST /tasks/{id}/agency-join-requests): the pending request, else the latest one Fluid declined while the work has no agency and no newer request, else null. An approved request is not shown (the work's `agency` says it), and neither is a cancelled one. Present wherever `agency_request` is, and left out, not null, wherever that is. It names the agency asked for, the state and the decline reason, and never the contact email, the note or who decided. A client sends its `lock_version` as `expected_version` when it cancels the request. anyOf: - $ref: '#/components/schemas/TaskAgencyJoinRequest' - type: 'null' merged_into: description: >- The ticket this one was merged into, or null for a ticket that is not merged (features/cowork, Phase 026). A merged ticket is `skipped`, frozen and has nothing to do but Split (POST /tasks/{id}/split). A deleted target is drawn with `deleted: true`, so the ticket can still be split. Present wherever `mist_confidence` is, and left out, not null, wherever that is. anyOf: - $ref: '#/components/schemas/MergedInto' - type: 'null' merged_from: type: array description: >- The tickets merged into this one, oldest merge first; empty when nothing was merged in. A merged ticket that was deleted is left out. Present wherever `mist_confidence` is, and left out wherever that is. items: $ref: '#/components/schemas/MergedFrom' conversation_id: type: - integer - 'null' description: >- The id of the ticket's messaging channel, the conversation in the company where the customer talks about the ticket, or null before the ticket's first send to an agency. A switch to another agency keeps it. Present only for a company with the COWORK feature flag on, and then wherever `agency_request` is; left out, not null, otherwise. Whether the reader may open the channel is up to Messaging. status_editable: type: boolean description: >- Whether the viewer may move this task's status now: the status rules hold (not sent to an agency; assigned to nobody or to the viewer; in a company without Cowork, always), Mist is not running it, and the viewer holds multiplayer_tasks.update or application_themes.update. Per viewer, so a client does not derive it. Present on the cards of the task list, a single task and the writes the task routes answer, wherever `agency_request` is, and left out, not false, wherever that is and for a caller that is not a user session. The status route still decides: this is a hint for the control, not the check. created_at: type: string format: date-time updated_at: type: string format: date-time StartRequest: type: object description: >- Browser Start intent and the one Desktop run it authorized, if any. It is not a task or run state machine. required: - id - client_id - expected_version - requester_id - requested_target_theme_id - requested_target_mist_id - accepted_run_id - accepted_by_id - accepted_target_theme_id - accepted_target_mist_id - accepted_at - acceptable - result - target - runner - action - reply - cloud_run - requested_by_bot properties: id: type: string format: uuid client_id: type: string format: uuid expected_version: type: integer minimum: 0 requester_id: type: integer requested_target_theme_id: type: - integer - 'null' requested_target_mist_id: type: - string - 'null' format: uuid description: >- The Mist app a publish of Mist app work names (target mist_app); null for work, which names its app only when claimed, and for a theme publish. accepted_run_id: type: - string - 'null' accepted_by_id: type: - integer - 'null' accepted_target_theme_id: type: - integer - 'null' description: >- The theme a theme request ran on; always null for a company_api or mist_app request. accepted_target_mist_id: type: - string - 'null' format: uuid description: The Mist app a mist_app request ran on; null for every other target. target: type: string enum: - theme - mist_app - company_api description: >- What Mist runs the work against. A theme request accepted on no theme reads company_api from then on; one accepted on a Mist app reads mist_app. runner: type: string enum: - desktop - cloud description: >- Where Mist runs the work, the requester's Mist Desktop or a cloud box. action: type: string enum: - work - publish description: >- What the run does, the task's work or a publish of the requester's cloud theme or Mist app work. reply: type: - string - 'null' description: >- The person's reply to what Mist's last run asked or said, for this run to read; null without one. cloud_run: description: >- The cloud box's run once Rails has started launching it, or a failed run with no box when the launch was refused or waited too long; null for a desktop request and for a cloud request still waiting for a box. anyOf: - $ref: '#/components/schemas/StartRequestCloudRun' - type: 'null' requested_by_bot: description: >- The bot that asked for this Start with the requester's own login, named in the X-Fluid-Bot-Id header and recorded for attribution only, so Cowork can say ", for ". The requester still accepts it like any Start. Null for a person's own Start. anyOf: - $ref: '#/components/schemas/StartRequestBot' - type: 'null' accepted_at: type: - string - 'null' format: date-time acceptable: type: boolean description: Current display hint. The server rechecks before accepting. result: description: >- Result of this accepted standalone run, or null before completion and for preview replies. anyOf: - $ref: '#/components/schemas/StartRequestResult' - type: 'null' Meta: type: object required: - request_uuid - timestamp properties: request_uuid: type: - string - 'null' timestamp: type: string format: date-time Error: type: object required: - error - status - meta properties: error: type: object required: - message - details properties: message: type: string details: type: object status: type: integer meta: $ref: '#/components/schemas/Meta' DiscussionDecisionResponse: type: object required: - id - actor - message_id - answers - text - action - task_id - start_request_id - created_at properties: id: type: string format: uuid actor: $ref: '#/components/schemas/Person' message_id: type: string format: uuid answers: type: - array - 'null' items: type: object required: - question_id - option_ids - custom_text - skipped properties: question_id: type: string option_ids: type: array items: type: string custom_text: type: - string - 'null' skipped: type: boolean text: type: - string - 'null' action: type: - string - 'null' enum: - save_task - assign_person - send_to_mist - send_to_studios - keep_discussing - null task_id: type: - string - 'null' format: uuid start_request_id: type: - string - 'null' format: uuid created_at: type: string format: date-time Person: type: object description: >- One person on a card. Mist is a person here, with a fixed id and no user row. required: - id - name - kind properties: id: type: string description: The user id as a string, or `mist` for the agent. name: type: - string - 'null' description: The name the server attributed, falling back to the email address. kind: type: string enum: - user - agent description: Whether this is a person or the agent. DiscussionAdminPage: type: object description: >- The admin page open beside the chat when a person sent a message. It records where they were, as their client reported it; it is not evidence that the record exists or that a reader may see it. A request's other keys in this object are ignored, as in every nested object of these requests. required: - type properties: type: type: string minLength: 1 maxLength: 64 pattern: ^[a-z0-9_-]+(/[a-z0-9_-]+)*$ description: >- The page's admin section, such as products, orders or settings/payments. id: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9_-]+$ description: >- The record the page shows, when it shows one; absent on a section page such as a list. MistResourceResult: type: object description: >- A product or order card projected from a saved api_get answer for the current reader. Facts stay as observed; the reader's grant for the source kind and the record's presence in the company are checked when the card is read. Model prose never creates a card. additionalProperties: false required: - receipt_id - request_id - tool_call_id - recorded_at - source_kind - source_id - state - observation - admin_path - api_path - required_permissions - summary properties: receipt_id: type: string maxLength: 256 description: Stable identity of the card within its saved read. request_id: type: string format: uuid description: The model attempt whose tool call made the read. tool_call_id: type: string maxLength: 128 description: The tool call that made the read. recorded_at: type: string format: date-time description: When the read was saved. source_kind: type: string enum: - product - order description: The kind of record. source_id: type: - string - 'null' pattern: ^[1-9][0-9]{0,18}$ description: The record id; null when the card is unavailable. state: type: string enum: - available - unavailable description: Unavailable when the record no longer exists in this company. observation: type: string enum: - list - detail description: Whether the card came from a list read or a detail read. admin_path: type: - string - 'null' pattern: ^/(products|orders)/[1-9][0-9]{0,18}$ description: The record's admin page; null when unavailable. api_path: type: - string - 'null' maxLength: 512 description: The API path that was read without its query; null when unavailable.: null required_permissions: type: array minItems: 1 maxItems: 1 description: The reader grant this card requires. items: type: string enum: - storefront.view - orders.view summary: description: Bounded facts from the saved answer; null when unavailable. anyOf: - $ref: '#/components/schemas/MistProductSummary' - $ref: '#/components/schemas/MistOrderSummary' - type: 'null' MistPageResult: type: object description: >- A storefront page Cowork read or captured, projected from its saved read_page or capture_page receipt for a reader already allowed to see the run or conversation. Restored without fetching the page again. Unavailable, with no URL, title or picture, when the page's host is no longer this company's storefront. additionalProperties: false required: - receipt_id - request_id - tool_call_id - recorded_at - kind - state - url - final_url - observed_at - title - viewport - screenshot_url properties: receipt_id: type: string maxLength: 256 description: Stable identity of the result within its saved read. request_id: type: string format: uuid description: The model attempt whose tool call read the page. tool_call_id: type: string maxLength: 128 description: The tool call that read the page. recorded_at: type: string format: date-time description: When the read was saved. kind: type: string enum: - text - screenshot description: A text read of the page as served or a captured screenshot of its visible part.: null state: type: string enum: - available - unavailable description: >- Unavailable when the page's host is no longer this company's storefront. url: type: - string - 'null' maxLength: 2048 description: The https URL that was requested; null when unavailable. final_url: type: - string - 'null' maxLength: 2048 description: The URL read after redirects; null when unavailable. observed_at: type: - string - 'null' description: When the page was fetched or captured; null when unavailable. title: type: - string - 'null' maxLength: 300 description: The page title from a text read; null for a screenshot. viewport: type: - object - 'null' description: The emulated viewport of a screenshot; null for a text read. additionalProperties: false properties: name: type: string enum: - mobile - desktop width: type: - integer - 'null' height: type: - integer - 'null' screenshot_url: type: - string - 'null' maxLength: 4096 description: >- The saved screenshot: the ImageKit URL of its DAM image asset while the asset is kept, or, for a capture saved in the private bucket before DAM storage, a signed URL valid for about ten minutes. Null for a text read or when the screenshot is unavailable. Agency: type: object description: >- An agency a customer can send work to, by the permanent key that names it in requests and the name people read. Agencies are records a root admin creates; no client names one in code. required: - key - name properties: key: type: string pattern: ^[a-z0-9_]+$ description: The agency's permanent key. name: type: string description: The name to show. examples: - key: example_agency name: Example agency SourceThread: type: object description: A preview discussion that contributes to a task, without its content. required: - id - theme_id - client_id - 'n' - page_url - author_name properties: id: type: integer description: The discussion's row id. theme_id: type: integer description: >- The theme the discussion is pinned on. Reading it needs the theme's own permission. client_id: type: string description: >- The client-generated id the preview clients address the discussion by. 'n': type: - integer - 'null' description: Display number shown on the pin. A label rather than an identifier. page_url: type: - string - 'null' description: Normalized path of the page the discussion was pinned on. author_name: type: - string - 'null' description: Who pinned it, attributed by the server. MistConfidence: type: object description: >- Mist's confidence that it could do the work as written, scored from the task's title, request, kind and plan before work starts. Present on the task list, a task, a write that answers with the task, and the board; absent where a task is embedded elsewhere. It only informs: no status, assignment, run or Start reads it. The state is derived from saved assessments and the task's current content, never from a queue. required: - state properties: state: type: string enum: - current - failed - out_of_date - assessing - not_assessed description: >- current: a score read the task's current content. failed: the newest attempt at the current content saved no score. out_of_date: the newest score read content the task no longer has, and a new one is on its way. assessing: no score yet, and one is on its way. A score is on its way only for work that has not started and was written to in the last 35 minutes. not_assessed: nothing is on its way: Cowork is off, work has started, or the task has not been written to since before assessment existed. The newest score, if any, comes with it. score: type: integer minimum: 1 maximum: 5 description: The newest score, from 1 to 5. Absent until one exists. band: type: string enum: - red - yellow - green description: >- The color the score reads as, decided by the server from the score alone, 1-2 red, 3 yellow, 4-5 green. summary: type: string maxLength: 280 description: Why the work earns the score, in at most two short sentences. concerns: type: array maxItems: 3 description: What holds the score back. A score below 5 has at least one. items: type: string maxLength: 200 raise_by: type: array maxItems: 3 description: What the person could add or decide that would raise the score. items: type: string maxLength: 200 assessed_at: type: string format: date-time description: When the newest score was saved. failure: type: string enum: - budget - provider - invalid_reply description: >- Why the newest attempt at the current content saved no score: the company's Mist budget refused it, the model call failed, or the reply did not meet the contract. Present only in the failed state. assessment_id: type: string format: uuid description: >- The read the newest score came from. Answers to its questions name it. Present whenever score is. suggested_kind: type: string enum: - bug - change - feature - design - support description: >- The kind of work Mist reads the task as. It never sets the task's kind; a person takes it with an ordinary kind update. This and the other triage fields come together, and only for a read that carries a triage: reads from before triage have none of them. category: type: string enum: - design - support - eng description: >- The department the suggested kind belongs to, derived from it - design, support, or eng for bugs, changes and features. difficulty: type: string enum: - easy - medium - hard description: How hard Mist rates the work. hours_low: type: integer minimum: 1 maximum: 160 description: >- The low end of the whole hours a skilled person would take. Hours, never money. hours_high: type: integer minimum: 1 maximum: 160 description: The high end of the hours range, no less than hours_low. questions: type: array maxItems: 3 description: >- What Mist needs to know from the task's creator, only when the read found something missing; empty for a read of 4 or 5. Answers go to answerMultiplayerTaskAssessment. items: $ref: '#/components/schemas/MistQuestion' duplicate_of: $ref: '#/components/schemas/MistDuplicate' TaskSource: type: object description: The outside issue a ticket was imported from. required: - provider - identifier - url properties: provider: type: string enum: - linear description: The outside work tool. identifier: type: string description: The issue's identifier in that tool, such as ACM-482. url: type: string description: Link to the issue in that tool. additionalProperties: false TaskAgencyRequest: type: object description: >- A task's request to its agency as the customer reads it. `state` is `sent` while the request is open, `done` once the customer accepted the work and `declined` once the agency declined it. `stage` says where open work stands, and a closed request keeps the stage it closed from. required: - agency - state - stage - version - sent_at - quote - revised_quote - changes_round - reopenable_until - delivery_overdue - last_step - owner - access - owner_has_access properties: agency: $ref: '#/components/schemas/Agency' owner: description: >- The agency member who picked the ticket up, who is the person to give access to by default. It is the only agency person the customer's read names apart from those given access. Null while nobody has picked it up, when the member's account is gone, and once the request is not open. anyOf: - type: object required: - id - name properties: id: type: string description: The user id as a string. name: type: string description: >- The member's name, or `Unnamed person`. It never falls back to their email. - type: 'null' access: type: array description: >- The agency people the customer gave access to their store from this ticket, each with the role they hold, ordered by name. Shown only to a reader who may manage that access (`users.update`, as `POST /agency-request/access` asks); any other reader gets an empty list, however many people were given access. Empty once the request is not open. items: $ref: '#/components/schemas/AgencyAccessEntry' owner_has_access: type: boolean description: >- Whether the agency member who picked the ticket up can get into the store: they were given access here, or hold an admin of their own. False while nobody has picked it up, and once the request is not open. Every reader sees it, whether or not they may manage access. state: type: string enum: - sent - declined - done stage: type: string enum: - requested - quoted - accepted - done_proposed description: >- `requested` waits for the agency's quote, `quoted` for the customer's answer, `accepted` is being built, and `done_proposed` waits for the customer to accept the work. version: type: integer minimum: 0 description: >- The request's version, sent back as `expected_version` by the answers. sent_at: type: string format: date-time quote: description: The current quote, or null while no quote stands. anyOf: - type: object required: - hours - deliver_on - note - quoted_at properties: hours: type: number description: The agency's estimate in hours. It is not a price. deliver_on: type: string format: date note: type: - string - 'null' quoted_at: type: string format: date-time - type: 'null' revised_quote: description: >- The quote the agency revised while building, waiting for the customer's answer (accept-revision or decline-revision), or null when none waits. anyOf: - type: object required: - hours - deliver_on - note - quoted_at properties: hours: type: number description: The agency's estimate in hours. It is not a price. deliver_on: type: string format: date note: type: - string - 'null' quoted_at: type: string format: date-time - type: 'null' changes_round: type: integer minimum: 0 description: >- How many times the customer has asked this agency for changes on the request. reopenable_until: type: - string - 'null' format: date-time description: >- Until when finished work (`state` `done`) may be reopened, 14 days after it was accepted. Null for any other request and once the time has passed. delivery_overdue: type: boolean description: >- True while the agency is still building (`stage` `accepted`) after the delivery date of the current quote, which is before today in UTC. False for any other request. last_step: description: >- The latest step on the request, or null for a request nobody has stepped on. anyOf: - type: object required: - kind - at - note properties: kind: type: string description: >- One of `sent`, `quoted`, `declined`, `quote_accepted`, `quote_declined`, `done_proposed`, `work_accepted`, `work_refused`, `withdrawn`, `quote_revised`, `revision_accepted`, `revision_declined`, `reopened`, `done_reminded`, `quote_reminded` or `delivery_missed`. A client treats a kind it does not know as a step it cannot name. at: type: string format: date-time note: type: - string - 'null' description: The quote or done note, or the reason a step gave. - type: 'null' TaskAgencyJoinRequest: type: object description: >- A task's ask for an agency Fluid does not have yet, as the customer reads it. `state` is `pending` while Fluid has not answered and `declined` once it has said no, with the reason in `decline_reason`. required: - id - state - agency_name - decline_reason - requested_at - lock_version properties: id: type: string format: uuid state: type: string enum: - pending - declined agency_name: type: string description: The name of the agency the customer asked for. decline_reason: type: - string - 'null' description: Why Fluid declined, or null while the request is pending. requested_at: type: string format: date-time lock_version: type: integer minimum: 0 description: >- The request's version, sent back as `expected_version` when it is cancelled. MergedInto: type: object description: The ticket another ticket was merged into. required: - id - title - deleted properties: id: type: string format: uuid title: type: string deleted: type: boolean description: >- Whether the target was deleted since. A merged ticket can still be split then. MergedFrom: type: object description: A ticket merged into the one that carries this list. required: - id - title - merged_at - version properties: id: type: string format: uuid title: type: string merged_at: type: string format: date-time version: type: integer minimum: 0 description: >- The merged ticket's `lock_version`, for a client's own cache. Split takes no version. StartRequestCloudRun: type: object required: - status - failure_reason properties: status: type: string enum: - launching - running - finished - failed - timed_out - cancelled failure_reason: type: - string - 'null' description: Why the run failed, when it did. StartRequestBot: type: object required: - id - name properties: id: type: string format: uuid name: type: string StartRequestResult: type: object required: - body - proof - finished_at properties: body: type: string proof: type: - string - 'null' finished_at: type: string format: date-time MistProductSummary: type: object description: Product facts as the API answered them; a missing value stays null. additionalProperties: false required: - title - sku - status - active - price - currency_code - in_stock - image_url - updated_at properties: title: type: - string - 'null' maxLength: 128 sku: type: - string - 'null' maxLength: 128 status: type: - string - 'null' maxLength: 128 active: type: - boolean - 'null' price: type: - string - 'null' maxLength: 128 currency_code: type: - string - 'null' maxLength: 128 in_stock: type: - boolean - 'null' image_url: type: - string - 'null' description: Present only for an image on the approved image origin. updated_at: type: - string - 'null' maxLength: 128 MistOrderSummary: type: object description: Order facts as the API answered them; a missing value stays null. additionalProperties: false required: - order_number - status - financial_status - fulfillment_status - created_at - customer_name - amount - currency_code - items_count - items properties: order_number: type: - string - 'null' maxLength: 128 status: type: - string - 'null' maxLength: 128 financial_status: type: - string - 'null' maxLength: 128 fulfillment_status: type: - string - 'null' maxLength: 128 created_at: type: - string - 'null' maxLength: 128 customer_name: type: - string - 'null' maxLength: 128 amount: type: - string - 'null' maxLength: 128 currency_code: type: - string - 'null' maxLength: 128 items_count: type: - integer - 'null' items: type: array maxItems: 10 items: type: object additionalProperties: false required: - title - quantity properties: title: type: - string - 'null' maxLength: 128 quantity: type: - integer - 'null' MistQuestion: type: object description: >- One question Mist asked in a read, answerable in a sentence or by picking an option. required: - id - prompt - options properties: id: type: string enum: - q1 - q2 - q3 description: The question's id within its read, in the order asked. prompt: type: string maxLength: 200 description: The question. options: type: array maxItems: 4 description: Likely answers to pick from; empty when the answer is free text. items: type: string maxLength: 80 MistDuplicate: type: object description: >- An older open ticket of the same company that Mist read this one as a repeat of (features/cowork, Phase 026). Present only while the suggestion stands: the state is `current`, the work has not started, the read named the ticket, the company has Cowork on, the other ticket still exists and is not closed, and nobody has merged or dismissed the pair. The key is absent, not null, otherwise. A suggestion informs and never merges: POST .../assessments/{assessment_id}/merge and .../dismiss are the person's. required: - id - title - status - reason - merge_blocked properties: id: type: string format: uuid description: The older ticket. title: type: string status: type: string enum: - open - kept - needs_info - in_progress - handed - review description: The older ticket's status now. reason: type: string maxLength: 200 description: One sentence of why Mist thinks the two repeat each other. merge_blocked: description: >- Why a merge into the older ticket would be refused now, or null. `agency`: it is sent to an agency. `running`: a Mist run holds it. `review`: it is in Review, whether or not a run put it there. `result`: it carries a run's result. The link is shown either way. anyOf: - type: string enum: - agency - running - review - result - type: 'null' AgencyAccessEntry: type: object description: >- An agency person given access to a company's store from a ticket, and their role. The customer's read lists them for a reader who may manage access; an agency member's read carries only their own. required: - person - role properties: person: type: object required: - id - name properties: id: type: string description: The user id as a string. name: type: string description: >- The person's name, or `Unnamed person`. It never falls back to their email. role: description: >- The role the person's admin holds, or null for an admin with no role. anyOf: - type: object required: - id - name properties: id: type: integer name: type: string - type: 'null' responses: DiscussionDecisionAnswered: description: The saved human response and any deterministic task outcome. content: application/json: example: decision: id: 01a1d0e2-fb35-7809-8370-c27b29d3e495 actions: - id: save_task label: Save task - id: assign_person label: Assign a person assistant_message_id: 01a1d0e2-fb54-797e-85a4-8d173344e056 created_at: '2026-11-12T17:51:38Z' kind: task_actions observed_task: null originating_run_id: 00e4d19e-1655-5076-a2bb-5fc72b33393b prompt: What should we do next? questions: [] response: id: 01a1d0e2-fc12-784d-a8a1-53f605744c5a actor: id: '433400890' name: Admin Acme kind: user message_id: 01a1d0e2-fbd0-72d2-98e4-cabfca0b8159 answers: null text: null action: save_task task_id: 01a1d0e2-fbed-7f11-a8ba-50f3f063810d start_request_id: null created_at: '2026-11-12T17:51:39.024Z' source_from_message_id: 00e4d19e-1655-5076-a2bb-5fc72b33393b source_through_message_id: 00e4d19e-1655-5076-a2bb-5fc72b33393b state: answered suggested_title: Review homepage copy message: id: 01a1d0e2-fbd0-72d2-98e4-cabfca0b8159 admin_page: null author: id: '433400890' name: Admin Acme kind: user body: Save task client_id: save-this-work created_at: '2026-11-12T17:51:38Z' discussion_id: 00e4d19e-1655-5076-a2bb-5fc72b33393b page_results: [] resource_results: [] role: human round_limit_reached: false sequence: 3 confirmation_message: id: 01a1d0e2-fc0c-78f7-a618-c3c91e3a6b08 admin_page: null author: null body: 'Saved task: Review homepage copy.' client_id: null created_at: '2026-11-12T17:51:39Z' discussion_id: 00e4d19e-1655-5076-a2bb-5fc72b33393b format: text page_results: [] resource_results: [] role: assistant round_limit_reached: false sequence: 4 task: id: 01a1d0e2-fbed-7f11-a8ba-50f3f063810d agency: null assignee: null assigner: null board_position: a0 board_position_at_ms: null category: null client_id: cowork_600a191a-d2c5-5500-9b52-502e746ce44c company_id: 96778814 created_at: '2026-11-12T17:51:38Z' creator_id: 433400890 description: |- Message 1 (person): What can you tell me about Fluid themes? Message 2 (assistant): What should we do next? Message 3 (person): Save task due_on: null kind: null lock_version: 0 plan: null priority: null run_id: null run_thread_id: null source_threads: [] status: open tags: [] title: Review homepage copy updated_at: '2026-11-12T17:51:38Z' start_request: null status: 200 meta: request_uuid: null timestamp: '2026-11-12T17:51:39Z' schema: type: object required: - decision - message - confirmation_message - task - start_request - status - meta properties: decision: $ref: '#/components/schemas/DiscussionDecision' message: $ref: '#/components/schemas/DiscussionMessage' confirmation_message: anyOf: - $ref: '#/components/schemas/DiscussionMessage' - type: 'null' task: anyOf: - $ref: '#/components/schemas/Task' - type: 'null' start_request: anyOf: - $ref: '#/components/schemas/StartRequest' - type: 'null' status: type: integer enum: - 200 - 201 meta: $ref: '#/components/schemas/Meta' securitySchemes: bearer_auth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.