> ## 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 an authenticated Start in Mist instruction > Requires a user session, company admin status, and multiplayer_tasks.execute or application_themes.update. The caller must name the task version it saw. The task must be open or kept, or needs_info for a desktop request or one with a reply; saving the request leaves its assignee as it is, and the run claim on acceptance gives unassigned work to the requester. The request remains pending while Desktop is closed. A cloud request (`runner: cloud`) instead queues a box Rails starts for it, and `runner: auto` lets Rails choose between the two. A ticket an agency is building, whose open agency request is `accepted` or `done_proposed`, is refused with 422 (`details.type` `agency_building`) until the agency's work is accepted or the request closes; a ticket at `requested` or `quoted` is not blocked. Its UUID is a reference, not a credential; a plain task URL never authorizes execution. An exact retry by the same requester and client id returns the original request without refreshing its task version or scope. A publish request (`action: publish`) puts the work the requester's saved cloud box keeps onto the theme or Mist app that work ran on, which Rails names; it needs application_themes.update for a theme, or mist.code for a Mist app, and work in review, and its run returns the work to review, or to needs_info when it could not publish. A publish of Mist app work saves target `mist_app` and fills `requested_target_mist_id` with the app, which its run pushes to. A We-Bots bot calls this with its owner's own login and names itself in `X-Fluid-Bot-Id`; a work request then records the bot in `requested_by_bot` (and the bot run it came from, whose conversation is told the cloud run's result and wakes the bot there). The header is attribution only: the owner is the requester and accepts the Start, on Mist Desktop or through the cloud runner, as for any Start. ## OpenAPI ````yaml /api-reference/multiplayer-v2026-04.yaml post /api/v202604/multiplayer/tasks/{id}/start-requests 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/tasks/{id}/start-requests: post: tags: - Mist runs summary: Save an authenticated Start in Mist instruction description: >- Requires a user session, company admin status, and multiplayer_tasks.execute or application_themes.update. The caller must name the task version it saw. The task must be open or kept, or needs_info for a desktop request or one with a reply; saving the request leaves its assignee as it is, and the run claim on acceptance gives unassigned work to the requester. The request remains pending while Desktop is closed. A cloud request (`runner: cloud`) instead queues a box Rails starts for it, and `runner: auto` lets Rails choose between the two. A ticket an agency is building, whose open agency request is `accepted` or `done_proposed`, is refused with 422 (`details.type` `agency_building`) until the agency's work is accepted or the request closes; a ticket at `requested` or `quoted` is not blocked. Its UUID is a reference, not a credential; a plain task URL never authorizes execution. An exact retry by the same requester and client id returns the original request without refreshing its task version or scope. A publish request (`action: publish`) puts the work the requester's saved cloud box keeps onto the theme or Mist app that work ran on, which Rails names; it needs application_themes.update for a theme, or mist.code for a Mist app, and work in review, and its run returns the work to review, or to needs_info when it could not publish. A publish of Mist app work saves target `mist_app` and fills `requested_target_mist_id` with the app, which its run pushes to. A We-Bots bot calls this with its owner's own login and names itself in `X-Fluid-Bot-Id`; a work request then records the bot in `requested_by_bot` (and the bot run it came from, whose conversation is told the cloud run's result and wakes the bot there). The header is attribution only: the owner is the requester and accepts the Start, on Mist Desktop or through the cloud runner, as for any Start. operationId: createMultiplayerTaskStartRequest parameters: - name: id in: path required: true description: Task UUID in the authenticated company. schema: type: string format: uuid - name: X-Fluid-Bot-Id in: header required: false description: >- The We-Bots bot making this call with its owner's login; attribution only. schema: type: string requestBody: required: true content: application/json: example: start_request: client_id: f70203a2-7712-4713-acf8-d4d0b8ad09af expected_version: 2 reply: 20% off, ending October 31 runner: cloud schema: type: object required: - start_request properties: start_request: type: object required: - client_id - expected_version properties: client_id: type: string format: uuid description: >- UUID allocated by the browser before the click is sent; reuse it only for an exact retry. expected_version: type: integer minimum: 0 description: Version of the task displayed when Start was clicked. target_theme_id: type: integer minimum: 1 description: >- Optional company theme chosen in the browser. Desktop chooses one if absent. Not allowed with the company_api target. target: type: string enum: - theme - company_api default: theme description: >- What Mist runs the work against. `theme` edits a local company theme. `company_api` asks Mist Desktop to make a requested business change through its own API tool, under the requester's current permissions; it names no theme and is refused for work from a preview discussion. A request never names a Mist app; the run that works on one says so when it claims the Start (`target_mist_id`). Only a publish of Mist app work is saved for its app, by Rails. Usually left out: Mist Desktop reads the work and accepts it on the theme it needs, or on none, which makes it company_api. runner: type: string enum: - desktop - cloud - auto default: desktop description: >- Where Mist runs the work. `desktop` is the requester's Mist Desktop. `cloud` is a box Rails starts and runs as the requester; it takes company_api or theme work, but not work from a preview discussion, needs the company's COWORK and MIST_CLOUD_RUNS flags, and only that box's run can accept it. `auto` asks Rails to choose when it saves the request: `cloud` when the company has both flags on and the work is not from a preview discussion, `desktop` otherwise, and `desktop` for needs_info work without a reply, which only Mist Desktop picks up. The saved request names the runner Rails chose, never `auto`, and an exact retry returns it. action: type: string enum: - work - publish default: work description: >- What the run does. `work` does the task. `publish` puts the work the requester's saved cloud box keeps onto the theme or Mist app it ran on, as Mist Desktop's Publish does for a theme, merging edits made on that theme meanwhile; it runs in the cloud (runner defaults to cloud), names no theme or app, and starts from work in review. reply: type: string minLength: 1 maxLength: 10000 description: >- The person's reply to what Mist's last run asked or said, for the next run to read with its brief. Work with a reply may also start from needs_info, where a run that needed something from the person left it, as may a desktop request, whose Mist can ask the person itself. Only a cloud request carries one; a publish takes none. responses: '200': description: Exact idempotent replay of an earlier Start instruction. content: application/json: example: task: id: 01a1d0e3-978f-7199-970d-00739dea4495 agency: null agency_join_request: null agency_request: null assignee: id: '433400890' name: Admin Acme kind: user assigner: id: '433400890' name: Admin Acme kind: user board_position: a0 board_position_at_ms: null category: null client_id: e6ba3421-865c-4ce0-ba44-e383b72b22c2 company_id: 96778814 conversation_id: null created_at: '2026-11-12T17:52:18Z' creator_id: 433400890 description: '' due_on: null kind: null lock_version: 2 plan: null priority: null run_id: 995057c9-989c-48ef-b33b-d1edd021b03b run_thread_id: null source_threads: [] status: review status_editable: true tags: [] title: Refresh the homepage updated_at: '2026-11-12T17:52:18Z' start_request: id: 01a1d0e3-9827-7ad5-b45c-bd965a96ee51 acceptable: true accepted_at: null accepted_by_id: null accepted_run_id: null accepted_target_mist_id: null accepted_target_theme_id: null action: publish client_id: 22ecaa34-ce24-4f74-8807-a0ff44a1a75e cloud_run: null expected_version: 2 reply: null requested_by_bot: null requested_target_mist_id: 01a1d0e3-977c-79cd-9b48-9b66a6b4ece0 requested_target_theme_id: null requester_id: 433400890 result: null runner: cloud target: mist_app status: 200 meta: request_uuid: null timestamp: '2026-11-12T17:52:19Z' schema: $ref: '#/components/schemas/StartRequestResponse' '201': description: Newly saved Start instruction; no run has been claimed. content: application/json: example: task: id: 9271f7b9-237c-5dbe-ab78-f866652d747a agency: null agency_join_request: null agency_request: agency: key: fluid_studios name: Test agency state: sent stage: quoted version: 0 sent_at: '2026-11-12T17:53:05.162Z' quote: null last_step: null revised_quote: null changes_round: 0 reopenable_until: null delivery_overdue: false owner: null access: [] owner_has_access: false assignee: null assigner: null board_position: null board_position_at_ms: null category: null client_id: acme-videos company_id: 96778814 conversation_id: null created_at: '2026-11-12T17:50:31Z' creator_id: 433400890 description: Use videos from the media library due_on: null kind: null lock_version: 0 plan: null priority: null run_id: null run_thread_id: null source_threads: [] status: open status_editable: false tags: [] title: Add customer videos updated_at: '2026-11-12T17:50:31Z' start_request: id: 01a1d0e4-4ce7-722c-b25b-41b1679a491e acceptable: true accepted_at: null accepted_by_id: null accepted_run_id: null accepted_target_mist_id: null accepted_target_theme_id: null action: work client_id: b9e43287-5f1d-411b-9f16-a8e85791dad9 cloud_run: null expected_version: 0 reply: null requested_by_bot: null requested_target_mist_id: null requested_target_theme_id: null requester_id: 433400890 result: null runner: desktop target: theme status: 201 meta: request_uuid: null timestamp: '2026-11-12T17:53:05Z' schema: $ref: '#/components/schemas/StartRequestResponse' '401': description: Authentication is required. '403': description: >- A user session, company admin status, and execution permission are required; a publish also needs application_themes.update, or mist.code when its work is on a Mist app. '404': description: The task is unavailable in this company. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The task version changed or this client id was used for another instruction. content: application/json: schema: $ref: '#/components/schemas/ConflictError' '410': description: >- The task was deleted while the Start instruction waited for its lock. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Invalid request, unsupported task state, assignment, or company theme; or a cloud request in a company without cloud runs, or for work from a preview discussion; or a publish that names a theme or a target other than theme, asks for Mist Desktop, carries a reply, is for work not in review, or has no cloud theme or Mist app work of the requester's to publish; work in needs_info without a reply; or a reply for Mist Desktop; or a ticket an agency is building (`details.type` is `agency_building`). content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearer_auth: [] components: schemas: StartRequestResponse: type: object required: - task - start_request - status - meta properties: task: $ref: '#/components/schemas/Task' start_request: $ref: '#/components/schemas/StartRequest' status: type: integer enum: - 200 - 201 meta: $ref: '#/components/schemas/Meta' 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' ConflictError: allOf: - $ref: '#/components/schemas/Error' - type: object properties: error: type: object properties: details: type: object required: - type properties: type: enum: - conflict - merged description: >- `conflict`: the version sent is stale. `merged`: the ticket was merged into another (features/cowork, Phase 026), so it is closed and frozen until it is split, and `merged_into` names the other ticket. Only a merged ticket answers `merged`, and only on a write that would change it; moving its card and deleting it still work. merged_into: type: object required: - id - title properties: id: type: string format: uuid title: type: string task: $ref: '#/components/schemas/Task' 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 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 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. 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 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' securitySchemes: bearer_auth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.