Skip to content

[ENG-2371] Publish complete OpenAPI responses for the documented Cowork routes - #541

Open
tino097 wants to merge 3 commits into
stagingfrom
tino097/eng-2371-fail-ci-when-the-cowork-api-reference-drifts-from-the
Open

tino097 wants to merge 3 commits into
stagingfrom
tino097/eng-2371-fail-ci-when-the-cowork-api-reference-drifts-from-the

Conversation

@tino097

@tino097 tino097 commented Sep 16, 2026 •

Copy link
Copy Markdown
Member

https://linear.app/mindsdb/issue/ENG-2371/fail-ci-when-the-cowork-api-reference-drifts-from-the-servers-openapi

What changed

  • publish complete OpenAPI responses for the documented Cowork routes: the
    task and conversation aliases, the Responses lifecycle routes, schedules,
    the artifact list and action routes, and search now declare their JSON
    success schema, and the conditional SSE and file routes declare their real
    media type, so the API reference drift check has a non-empty server schema
    to compare against instead of {}
  • Merge origin/staging so the documented routes keep their dependency gates
    alongside the OpenAPI response metadata: staging had added org-mode and
    desktop-only gates on the same nine decorators, so those routes now carry
    both

Why this matters

Reviewing mindsdb/mindshub#12493 by hand found 18 of the 52 documented
endpoints do not exist and 20 of 26 checked response cards misdescribe the
server. The drift check that will guard the page reads app.openapi(), which
today emits an empty success schema for these routes, so there is nothing for
it to compare. This PR fills those schemas without touching wire behavior.

Notes for the reviewer

  • Metadata only, not response_model. Schemas are declared through
    FastAPI's responses= so returned payloads are neither filtered nor
    coerced. Existing endpoint tests remain the guard on serialization and
    tenant scoping.
  • Server-only routes are not declared. Only the operations the public
    reference publishes get schemas; the desktop, coding-runtime, settings,
    and compatibility routes are unchanged.

Ships with

The mindshub checker PR, not yet open. This PR is independent and can merge
first.

Checks

Check Observed result
uv run pytest tests/test_openapi_contract.py 4 passed, before and after the merge
make test/unit 4,732 passed, 2 skipped after the merge (3,921 passed, 3 skipped on the original commit)

🤖 Generated with Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 70fc0c6811

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +916 to +917
"application/octet-stream": {
"schema": {"type": "string", "format": "binary"}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Advertise the media types the file route actually returns

When serving files with recognized extensions such as index.html, styles.css, or images, this route derives and returns text/html, text/css, or the relevant image type via mimetypes.guess_type(); application/octet-stream is only its fallback. Advertising only the fallback therefore gives the reference and generated clients an incorrect content-type contract for the normal success paths. Declare a wildcard/media-type ranges or enumerate the supported response types while retaining the binary schema.

Useful? React with 👍 / 👎.

…ates alongside the OpenAPI response metadata

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

No PR environment for this pull request

Add the deploy label and push to create one. It is torn down when the label is removed or the PR closes, so any URL you saw here earlier is gone.

Updated on every push to this PR.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@lucas-koontz
lucas-koontz force-pushed the tino097/eng-2371-fail-ci-when-the-cowork-api-reference-drifts-from-the branch from 2c9265e to a53f013 Compare October 18, 2026 05:52

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant