> ## 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. # Keep the original quote > Requires a company-admin user session with multiplayer_tasks.execute and the company's COWORK feature flag, as sending work to an agency does; planning permission alone is not enough. The answer writes the agency request and one event and does not change the task's status, owner or version. It is posted to the task's channel when it has one. Turns down the revised quote the agency sent while building (`agency_request.revised_quote`) with a reason, and the original quote stands. The revision stays in the request's record. The stage and the resolve clock do not move. It is allowed while the request is `accepted` or `done_proposed`; with no revised quote waiting, or any other stage, it answers 422. ## OpenAPI ````yaml /api-reference/multiplayer-v2026-04.yaml post /api/v202604/multiplayer/tasks/{id}/agency-request/decline-revision 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}/agency-request/decline-revision: post: tags: - Agency requests summary: Keep the original quote description: >- Requires a company-admin user session with multiplayer_tasks.execute and the company's COWORK feature flag, as sending work to an agency does; planning permission alone is not enough. The answer writes the agency request and one event and does not change the task's status, owner or version. It is posted to the task's channel when it has one. Turns down the revised quote the agency sent while building (`agency_request.revised_quote`) with a reason, and the original quote stands. The revision stays in the request's record. The stage and the resolve clock do not move. It is allowed while the request is `accepted` or `done_proposed`; with no revised quote waiting, or any other stage, it answers 422. operationId: declineMultiplayerTaskAgencyRevision parameters: - name: id in: path required: true description: The task UUID returned at creation or in a task page. schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - agency_request properties: agency_request: type: object required: - reason - expected_version properties: reason: type: string minLength: 1 maxLength: 2000 description: Why. The agency reads it. expected_version: type: integer minimum: 0 description: >- The `agency_request.version` of the task the client read: the request's version, not the task's `lock_version`. A request that changed or closed since answers 409. example: agency_request: reason: The extra hours are too many expected_version: 3 responses: '200': description: >- The task, whose `agency_request.revised_quote` is now null and `agency_request.quote` is unchanged. content: application/json: example: task: id: 01a1d0e3-e59b-73e8-8ea0-ea3dd6df305c agency: key: fluid_studios name: Test agency agency_join_request: null agency_request: agency: key: fluid_studios name: Test agency state: sent stage: accepted version: 4 sent_at: '2026-11-12T17:52:38.813Z' quote: hours: 6.5 deliver_on: '2026-11-15' note: Two short videos quoted_at: '2026-11-12T17:52:38.828Z' last_step: kind: revision_declined at: '2026-11-12T17:52:38.924Z' note: Too many hours revised_quote: null changes_round: 0 reopenable_until: null delivery_overdue: false owner: id: '433400890' name: Admin Acme access: [] owner_has_access: true assignee: null assigner: null board_position: null board_position_at_ms: null category: null client_id: decline company_id: 96778814 conversation_id: null created_at: '2026-11-12T17:52:38Z' creator_id: 433400890 description: '' due_on: null kind: null lock_version: 1 merged_from: [] merged_into: null mist_confidence: state: assessing plan: null priority: null run_id: null run_thread_id: null source_threads: [] status: open status_editable: false tags: [] title: decline updated_at: '2026-11-12T17:52:38Z' status: 200 meta: request_uuid: null timestamp: '2026-11-12T17:52:38Z' schema: type: object required: - task - status - meta properties: task: $ref: '#/components/schemas/Task' status: const: 200 meta: $ref: '#/components/schemas/Meta' '401': description: Authentication is required. '403': description: >- A user session, company admin status, and execution permission are required. '404': description: >- The task is unavailable in this company, or the company does not have Cowork. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The request changed or closed since the client read it (`details.type` is `conflict`). The current task is included in `details.task`, with its `agency_request`. A step repeated after its response was lost answers this too, with the task showing the step applied. content: application/json: schema: $ref: '#/components/schemas/ConflictError' '410': description: The task was deleted after it was read and before the answer landed. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- The body is invalid, or no revised quote waits or the request's stage does not allow the answer (`details.type` is `invalid`, with the task in `details.task`). content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearer_auth: [] components: schemas: 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 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' 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' 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. 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.