Daily, Oct 9 - #9
Merged
Merged
Conversation
kraftp
marked this pull request as ready for review
October 10, 2023 19:13
kraftp
approved these changes
Oct 10, 2023
devhawk
added a commit
that referenced
this pull request
Aug 17, 2026
Conductor's HTTP API and the `dbosctl` CLI had no documentation. This adds two pages under **Deploy To Production** and links them from the Conductor overview. Both are new files, so the diff is additive — nothing existing is rewritten beyond one bullet on `conductor.md`. ## The pages **[Conductor API](docs/production/conductor-api.md)** — base URLs, the three ways to get the OpenAPI spec, authentication, resource scoping, the RFC 9457 error model, listing and filtering conventions, a map of all 64 operations by area, the operations a no-auth self-hosted deployment does not register, and how to generate a client. **[dbosctl CLI Reference](docs/production/dbosctl.md)** — installation, profiles, authentication, configuration precedence, output formats, exit codes, and a command-by-command reference. Follows the shape of the existing Cloud CLI reference page. The sidebar is autogenerated from the directory, so no `sidebars.js` change is needed. ## Where the content came from Not from the READMEs. The endpoint reference, parameter lists, and error shapes were read out of the OpenAPI spec, and the CLI reference was generated from a recursive `--help` dump of a real build, then diffed back against it mechanically — 38 leaf commands, no undocumented commands, no invented flags. Details that came from reading the implementation rather than the spec text, because a reader would otherwise hit them as surprises: - **Workflow mutations need a live executor.** Cancel, resume, restart, fork, and delete are dispatched to a healthy connected executor rather than applied in Conductor's database, so they fail outright when nothing is running — resume and restart additionally need an executor on the latest version. - **The autoscaling operations require a DBOS Teams plan** and return 403 otherwise. - **Getting the spec from the Conductor image needs `--entrypoint`.** The image's entrypoint waits for Postgres and runs migrations without forwarding arguments, so the obvious `docker run <image> openapi` hangs waiting for a database the subcommand does not need. ## Two scoping calls worth a look **The API is not "everything the console does."** An earlier draft said so; it is wrong, because the console also drives DBOS Cloud — deploying applications, provisioning databases, billing — none of which this API touches. Both pages now scope it to the Conductor control plane, which is what the console shows for a Conductor-connected application whether it runs on your own infrastructure or on DBOS Cloud, and point the cloud-specific operations at the pages that own them. **Nothing is framed as versioned.** There is one public API; the predecessor is internal. `v2` appears only in URLs and paths, where you actually type it, and never in prose as though it were a choice. ## Verified against the shipped API The pages track conductor `main` as of the `applicationName` revert (dbos-inc/dbos-conductor#187) and the CLI as of dbos-inc/dbos-ctl#8 and #9: - the `listWorkflows` query parameters and the full workflow-search body field list match the spec exactly; - all 64 operations appear in the endpoint tables, and all 16 OAuth-gated operations are named by operation ID; - `applicationName` is documented as a **response** field only — the request filters were removed by #187; - install instructions follow the `dbos-cli` → `dbos-ctl` repository rename and lead with the new install script. The site builds. The only broken-anchor warnings are pre-existing ones on the Go reference pages, untouched by this branch. ## One sequencing note The `dbosctl` page links to the CLI's releases page and its `raw.githubusercontent.com` install script, both of which are only reachable once that repository is public and a release is tagged. The page carries an early-access admonition, so it is not misleading in the meantime, but this probably wants to land alongside that flip. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.