docs: correct Coder Agents API paths and required organization_id - #28573
docs: correct Coder Agents API paths and required organization_id#28573nickvigilante wants to merge 8 commits into
Conversation
The chat surface mounts under /api/experimental, not /api/v2. Update every Coder Agents doc that referenced /api/v2/chats, including the Tasks to Chats endpoint mapping table and the curl and websocat examples. Also add the required organization_id field to the create-chat example in the getting started guide, matching the migration guide.
Docs previewCheck off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.
|
|
Hold for #28482. That PR rewrites the same Generated by Coder Agents on behalf of @nickvigilante. |
Coder Agents settings now belong to an organization. Document the new scope split, the permissions that control edit access, and the new Organization settings section that holds model overrides. Add a new "Organization scope" page. Update the models, getting started, platform controls, MCP servers, advisor, architecture, and migration pages for the new scope. Correct stale breadcrumbs and API routes.
…odel wording Remove implementation details from the organization scope documentation. Correct the Advisor and Virtual desktop locations to the Deployment settings section. Correct the Add model and Add server button labels. Replace the star action with the Default badge and the model form option. Document that the first model of an organization becomes its default.
…oped-admin-configuration-for-agents' into vigilante/docs-719-correct-coder-agents-api-paths-apiv2-apiexperimental-and # Conflicts: # docs/ai-coder/agents/getting-started.md # docs/ai-coder/agents/platform-controls/chat-debug-logging.md # docs/ai-coder/agents/tasks-to-chats-migration.md
|
Now stacked on #28482 per the plan above: base re-targeted to its branch, conflicts resolved in a merge commit (kept its org-scoped models route and Admin settings navigation, applied the /api/experimental prefixes on top). Will re-target to main once #28482 merges. Generated by Coder Agents on behalf of @nickvigilante. |
|
@ethanndickson @mattvollmer I think Coder Agents (the tool used to construct this PR) thought that Coder Agents' API routes were not updated. Matt, I remember your PR where we updated the routes, so if this PR is garbage, just say so and I'll close it. |
|
Yep pls close |
…rrect-coder-agents-api-paths-apiv2-apiexperimental-and # Conflicts: # docs/ai-coder/agents/getting-started.md # docs/ai-coder/agents/platform-controls/chat-debug-logging.md # docs/ai-coder/agents/tasks-to-chats-migration.md
2 participants
Coder Agents docs pointed API consumers at
/api/v2/chats, but the entire chat surface is registered under/api/experimental. Every affected path is corrected, and the create-chat example in the getting started guide now includes theorganization_idfield thatpostChatsrequires./api/v2/chatswith/api/experimental/chatsacrossdocs/ai-coder/agents/, including the Tasks to Chats endpoint mapping table and all curl, websocat, andwss://examples.organization_idto the create-chat example ingetting-started.md, with a note that the caller must be an organization member and can find the ID viaGET /api/v2/organizations.docs/reference/are untouched; they already use the experimental paths.Linear: DOCS-719 https://linear.app/codercom/issue/DOCS-719
Analysis evidence
Route registration (
coderd/coderd.go):r.Route("/api/experimental", func(r chi.Router) {with the comment that experimental routes are not guaranteed to be stable.r.Route("/chats", func(r chi.Router) {nested inside that experimental route, covering/,/watch,/files,/models(line 1437, registered at the experimental root as a default-organization shortcut),/config/*,/providers,/user-provider-configs, and/{chat}/...(/messages,/stream,/interrupt,/debug/runs,/debug/runs/{debugRun})./api/v2route block begins after the experimental block closes, so no/api/v2/chatsroute exists.spend-management.md(/cost/users,/cost/{user}/summary) were also registered under/api/experimental/chatswhen they existed (commit1482cdd11b).Required
organization_id(coderd/exp_chats.go,postChats):if req.OrganizationID == uuid.Nilreturns400withMessage: "organization_id is required.".httpmw.UserAuthorization(ctx).HasOrganizationMembership(req.OrganizationID).tasks-to-chats-migration.mdalready documented both the field and the membership rule, so the two pages are now consistent.Validation:
pnpm install --frozen-lockfile,pnpm run format-docs, andpnpm run lint-docsall run clean (0 errors, 499 files linted). Only the nine intended files are modified.Generated by Coder Agents on behalf of @nickvigilante.
Stacked on #28482. This PR targets
ethan/codagt-715-document-org-scoped-admin-configuration-for-agentsand merges that branch in, resolving the shared edits (tasks-to-chats-migration.mdendpoint table,getting-started.mdsystem-prompt line,chat-debug-logging.md) by combining that PR's navigation and org-scoped models route with this PR's/api/experimentalprefixes. Re-target tomainafter #28482 merges.