Conversation
… (ENG-2207) - Remove the Use Cases page and its nav/card links across the site. - Rebrand the Cowork API reference as the Tasks API: page title, meta tags, hero copy, sidebar, and the Conversations section (now Tasks, with Conversations noted as the same underlying concept). - Flip the ERD's primary entity label to Task (= Conversation) and repoint its anchors/comments accordingly. - Add a Local/Hosted toggle for the Base URL strip and every curl example, so readers can switch to https://cowork.mindshub.ai/api/v1 (MindsHub-hosted) instead of the local server. Prose describing the resource ("filter to a task", "attached to a task") is updated throughout; literal API field names and enum values (conversation_id, "type": "conversation") are left as-is since that's what the server actually returns.
…st toggle - Move Tasks before Responses and fold Responses in as a "Streaming a task" subsection of Tasks, matching the Scratchpads/Cells nesting pattern already used on this page. - Audit the streaming docs against the real cowork-server code and fix what had drifted: the create-turn body param is `conversation`, not `conversation_id`; `stream` defaults to false, not true; `skill_ids` isn't a real field; /responses/in-flight-list takes no query params. - Document the previously-undocumented GET /responses/tail (resume a stream from `from_seq`, replaying from 0 or from wherever you left off) and POST /responses/cancel, and rewrite the response/stream examples to match the real Response/StreamingResponse schemas. - Base URL toggle: made it sticky under the nav while scrolling, reordered Hosted before Local, and defaults to Hosted.
Every endpoint badge (GET /tasks, POST /responses, etc.) now renders as the full request URL under the currently selected base, via a data-path attribute the toggle script rewrites — matching how the curl examples already behave.
Create-first reads better for these three — you make a task/project before you list them, and uploading is the natural entry point for Files. Endpoint order elsewhere is unchanged.
Each "X object" schema (Task, Project, Artifact, Schedule, File, ConnectorSpec, Connection, Memory, Skill, Scratchpad/Cell) now lives inside the GET endpoint that actually returns it, labeled "Response — X object", instead of floating above the endpoint list. Search already showed its response inline; dropped the now-redundant standalone SearchResult block above it.
The "Run it locally or hosted" card said in prose what the toggle already does interactively — drop the card and put the toggle in its place, right under the lede, instead of further down past the ERD.
… relationships - Task now sits side by side with Project instead of below it. - Schedule, File, and Artifact each get a relationship to both Project and Task (dashed/optional to Task, since attaching to an existing task is optional on all three) — previously they only showed the Project edge. - Removed the Response and Cell entity boxes; the diagram now covers Project, Task, Artifact, Schedule, File, Connector, Memory, Skill, and Scratchpad. - Dropped the redundant Connector "usable within" line so Connector matches Skill's independent/no-line styling; simplified the legend to three entries accordingly. - viewBox shrunk (760x360 -> 760x300) since removing two rows freed vertical space.
…in the ERD Move File into the right-hand column under Skill, pluralize all four resource box labels, and wrap them in a dashed group box labeled "Agent Task Resources". Rerouted Project/Task -> File through the Memory/Skill gap to reach the new position, and moved the legend into a single horizontal band below Scratchpad since the old bottom-right spot is now the group box.
…hen Task->Artifacts - Remove the Schedule box and its two edges (including the "triggers" line) from the diagram — the Schedules API section itself is untouched, this is diagram-only. - Artifacts and Scratchpad now sit on the same row/level. - Task -> Artifacts is now a solid "owns" line instead of a dashed optional one. - Pluralized "Artifact" -> "Artifacts". - Scratchpad's subtext is now "agent coding execution environment". - Legend drops the now-unused "triggers" wording and moves up since the diagram is shorter (viewBox 760x330 -> 760x272).
Files now sits in the resources group with no incoming lines, same as Connectors and Skills. Task box gets a subtitle, "agent task scope of work", matching Project's "central workspace".
Memories joins Connectors, Skills, and Files in the resources group with no incoming lines. Dropped the "optional" legend entry and the dashed-arrowhead marker def since no dashed relationship lines remain in the diagram, and shrunk the legend to the two entries still in use.
- Connectors: "independent" -> "apps and data" - Memories: "global or project" -> "self learnings storage" - Artifacts: "mini app" -> "apps, presentations, documents" — widened the Artifacts box and its badge to fit, and shifted Scratchpad over to match so the row stays level and clear of the resources group.
Shown only when MindsHub Cloud is selected, right-aligned next to the URL, linking to https://console.mindshub.ai/apiKeys. Hidden when Your Server is selected, since a local server needs no key.
The box now shows "agent task outputs" as plain subtext, matching the other resource boxes. The purple "apps, presentations, documents" pill moves outside the box, floating just beneath it.
Project now uses the plain border style like the other resource boxes. Task keeps the accent glow, since it's the entity the Agent Tasks API is built around.
Tag changes from "Hosted API" to "Inference API"; body copy simplifies to "For the MindsHub Model-Router API, see the Inference API docs", dropping the old "these pages document Cowork..." framing.
…owork-App - Brand text: "MindsHub Cowork" -> "MindsHub Agents" - Nav links: "Setup" -> "Cowork-App", "API" -> "Agents API", "Hosted API" -> "Inference API" - Applied consistently across index.html, api.html, and setup.html
Plain-language walkthrough of the diagram: projects organize tasks, tasks need scratchpads to do real work, task output becomes artifacts, and agents draw on shared connectors/files/memories/skills.
Checked docs/api.html's Tasks section against cowork-server's actual
ConversationCreateRequest/UpdateRequest/ListItem schemas and endpoint
handlers. Found and fixed:
- "goal" and "status" don't exist anywhere in the real schema/model —
removed from the create body, the Task object example, and the
PATCH body (which was titled "Update title, goal, or status").
- The real create body accepts topic, title, project, project_id,
harness, model — only project_id/title were documented.
- List query params are project_id, project, limit — not status/offset,
which don't exist on the endpoint.
- project_id is a required, non-nullable column on the model (every
task defaults to the account's default project) — the object example
wrongly implied it could be null for an unscoped task.
- Get-messages takes no query params — limit/before were fictional.
- Two real endpoints were entirely undocumented: POST /tasks/{id}/move
(project + artifact relocation) and DELETE /tasks/{id}/turns/{n}.
Added both.
- Documented the actual response fields (preview, project, project_path,
harness, model, reasoning_effort) in place of the old goal/status
shape.
Note for follow-up outside docs: reasoning_effort is accepted by the
create request schema and the service layer, but the endpoint handler
never passes it through — it's silently dropped today, so it's
intentionally left undocumented as a create-time param rather than
described as working.
Every curl example (21 across the page, including the two-invocation Memories block) now carries an -H "Authorization: Bearer YOUR_API_KEY" line, wrapped so the toggle can show/hide it. Visible by default (MindsHub Cloud is the default selection) and hidden when Your Server is selected, since the local server takes no API key.
Headers belong after the method+URL line, grouped with other -H flags — not before it. Moved the auth line accordingly: right before the existing Content-Type header on JSON POST/PATCH examples, before the -F flags on the file upload example, and appended as a new continuation line on GET examples that previously had none (including the two-invocation Memories and responses/tail blocks, where the trailing comment now sits after the auth line instead of mid-command). Also fixed a real bug in the single-line-to-multi-line conversions: the backslash continuation now lives *inside* the hidden span so switching to Your Server removes the whole continuation instead of leaving a dangling trailing backslash.
- Every code block gets a Copy button (delegated click handler, so it works on dynamically cloned blocks too). Copies pre.innerText, which naturally excludes the hidden Authorization line when Your Server is selected. - New sticky right-hand panel (3-column layout above 1200px) that mirrors the curl example and, when one exists, the labeled response example of whichever endpoint is currently scrolled into view. Updates on scroll and re-renders on Local/Hosted toggle so it never shows stale base-URL text. - Panel and sidebar collapse together below 1200px; sidebar alone collapses below 768px as before.
Dropped the global scroll-tracking side panel (JS-heavy, and its cloned content could go stale) in favor of a simpler, more robust layout: each endpoint whose body has a curl example and/or a labeled response schema now splits into two columns — params/explanation on the left, curl + response on the right — via plain CSS grid, no JS. Endpoints with nothing to put on the right (no curl, no response) or nothing to put on the left (params-free curl-only examples) stay single-column. Shell reverts to its original 2-column (sidebar + content) layout; copy buttons stay, unaffected by the layout change.
- Params table: type and required/optional now stack on separate lines within one cell instead of two cramped nowrap columns — reads better now that tables sit in the narrower left column of the two-column endpoint layout. - All code cards (curl and response alike) get a consistent 5px top margin via the shared .code-block rule.
…dpoints) Final pass confirms all 52 endpoints now show both a curl example and a response card.
|
Reviewing this now. One question first, because the answer changes what I'd comment on. Which name is intended for the API reference, and has it been agreed beyond this PR? I'm seeing four answers:
"Agents" and "MindsHub Agents" don't appear on mindshub.ai today. The site's API names are Inference API and Console API. Its product names are Cowork, Cowork Cloud, MindsHub Inference / Model-Router and Air. ENG-2170 is open on this exact problem — seven user-facing names, none defined. It lists renaming products as out of scope. The I'll start on the endpoint and param work now either way. That part is name-independent, and from a skim it's the substantial half of the PR. It's the headings, meta tags and nav labels I'd rather not review twice. |
|
Endpoint findings, independent of the naming question. 1. Eighteen of the 52 documented endpoints don't exist as writtenChecked against
The Tasks section is clean. All eight The gap is the 52-endpoint completeness pass. It added curl examples and response cards to nine scratchpads endpoints that have never existed. A scripted inventory can confirm every endpoint has a card, but not that the endpoint is real, which is why it returned 0/52 missing. 2. The toggle defaults to hosted, where
|
Dav1dF
left a comment
Dav1dF
left a comment
There was a problem hiding this comment.
Requesting changes. Two blockers.
What holds up: CI is green, both test-plan claims verify (tag balance under a real parser, node --check on all three scripts), and the /tasks and /responses sections are accurate against the server.
1. Response cards: 20 of the 26 I checked misdescribe the server
The base file had no per-endpoint response cards, so this PR added all 52. Five of the six section shapes it reused were already wrong, and each was copied into several cards.
| Section | Card says | Server |
|---|---|---|
| Schedules | "cron": "0 9 * * 1", "status": "active" |
cadence enum (once/hourly/daily/weekdays/weekly), enabled: bool. No cron field exists; the section blurb is wrong too |
| Files | {name, mime_type, size, project_id, conversation_id} |
OpenAI Files shape: {id, object, bytes, created_at (int epoch), filename, purpose} |
| DELETE x4 (projects, schedules, files, skills) | {"ok": true} |
204 NO_CONTENT, empty body |
| Skills | "instructions", "tools": [...] |
serializes as declarative; no tools field on the model |
| Projects | description, connector_ids, skill_ids, updated_at |
none exist; it is modified_at. Missing required path, is_active, attribution, capabilities |
| Connector specs | "name", "auth_type", "fields[].key" |
label; no auth_type on any connector model; ConnectorField key is name |
| Connections | "id", "spec_id", "status": "connected" |
keyed on (engine, name); engine; status is null when healthy, "needs_reconnect" when not |
| Artifacts | type: app/report/doc/dashboard, created_at, updated_at |
html-app/document/dataset/image/mixed/fullstack-*; no creation timestamp; updated is a human string. type is also a query filter, so the filter values fail too |
| Search | total, excerpt, score: 0.93, type: conversation |
{results: [...]} only; subtitle; _score is an unbounded int; emits task/project/artifact/schedule/pin |
Several of these sections serialize camelCase (nextRunAt, createdAt, projectId). The cards show snake_case throughout.
Separately, 18 of the 52 documented endpoints do not exist — detail in my earlier comment. Nine /scratchpads endpoints now carry worked curl examples and response cards for routes that have never existed.
GET /artifacts/preview, POST /artifacts/open and /artifacts/serve/... all carry require_local_tenancy, so they cannot succeed against the hosted base URL the page defaults to.
2. Deleting Use Cases drops an indexed URL with no redirect
/cowork/use-cases.html returns 200 today with <meta name="robots" content="index, follow"> and no canonical. /use-cases.html 301s to it. Unmatched paths 404 with no fallback, so both go dead on merge.
Nothing in this repo still links to it and it is in no sitemap, so the fix is not here: it is a LEGACY_COWORK_PAGES entry in mindsdb/mindshub_inference docs/router/router.js, plus a manual wrangler deploy. docs/router/verify.mjs:64 also asserts that URL returns 200 and will begin failing.
Suggested path
Land the /tasks section, the Inference API rename and the base-URL toggle. Delete the scratchpads and memories sections rather than repathing them. For the rest, generating the reference from the FastAPI schema would cost less than another manual pass and would stop this recurring; I can raise that separately.
|
Raised the docs-generation follow-up as ENG-2371, so it is tracked separately from this PR. |
|
Naming update: Costa proposed simplifying the product names (MindsHub + MindsHub Inference) and I've raised the API-name question – Tasks API vs Agents API – with Jorge on Slack, with Tasks API as the proposal. Holding the headings/meta/nav-label part of this review until that's decided; the endpoint findings above stand either way. |
2 participants
Summary
Rebrands the Cowork docs API reference as the Agents API, promoted around a Task-centric model, with a fully reworked ERD, a Local/Hosted base-URL toggle, and complete curl+response coverage for every endpoint.
Branding
MindsHub Cowork→ MindsHub Agents;Setup→Cowork-App;API→ Agents API;Hosted API→ Inference API.Tasks API content
/conversations→/tasksthroughout (paths, headings, prose); "Tasks and Conversations are the same concept" called out; literal field names/enum values left as-is since that's what the server actually returns.cowork-servercode and fixed real drift: removed fictionalgoal/statusfields, corrected the create/list/update body & query params, fixed the non-nullableproject_idclaim, documented the real response shape, and added two previously-undocumented endpoints (POST /tasks/{id}/move,DELETE /tasks/{id}/turns/{turn_index})./responseslifecycle including the previously-undocumentedGET /responses/tail(resume viafrom_seq) andPOST /responses/cancel.ERD diagram
Base URL toggle
https://cowork.mindshub.ai/api/v1) with Your Server as the alternate.console.mindshub.ai/apiKeys.Authorization: Bearerheader, correctly ordered after the method+URL line and hidden when Your Server is selected.Page layout & completeness
Linear: https://linear.app/mindsdb/issue/ENG-2207
Test plan
<div>/</div>,<span>/</span>,<table>/</table>,<p>/</p>,<pre>/</pre>) after every structural change.node --checkon the extracted page JS after every script change.🤖 Generated with Claude Code