Repository navigation
agents: document Harness Runtime under /v2/harness-runtime - #1302
mishraishika24-pixel wants to merge 4 commits into
Conversation
The Harness Runtime API is reachable at /v2/harness-runtime: the edge authorizes the new prefix and rewrites it onto /v2/agents, with no service change. Move the documented path keys, the prose that names them and the curl examples over to it. operationIds, tags, parameters and request/response shapes are unchanged, so a generated client keeps its method names and only the URL it builds moves. /v2/agents keeps serving identical responses for callers on an older client. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
2b797bd to
b36f751
Compare
|
Merge gate: confirm the edge rewrite is live everywhere before this publishes This PR documents The edge authorization for the new prefix is already merged. I couldn't verify that the rewrite is deployed on every host that carries Could the owner of the edge rewrite confirm it is deployed on all of them? Until then I'd hold the merge. |
|
Suggested change:
The second point matters because this URL gets pasted into GitHub, GitLab and Slack. Those can't be updated when the prefix changes, so the old spelling has to stay valid permanently, and the docs shouldn't imply it is deprecated. |
|
Checked both. Edge rewrite. Live on the hosts named above. Unauthenticated
|
The trigger service still writes /v2/agents into webhook_url, so the example has to match that response. Both spellings of the webhook path stay accepted, and callers paste the returned URL unchanged.
|
Done in 6aa3e75.
|
…g is used Moves the path and the curl example to /v2/harness-runtime/regions. #1302 moves the documented Harness Runtime surface to that prefix and names this PR; a new route under /v2/agents would conflict with it. Rewrites the descriptions. They said a returned slug "is accepted as the region a session or config is created in", which reads as a placement choice. create_session_request.region says the opposite: the session is always created in the region whose API host served the request, and the body field is only a check against that host. The slug now names the host to call, is_default names the region the region-less host serves, and the operation says what a team outside the regional routing rollout sees. Reported in review by @DO-rrao.
* agents: document GET /v2/agents/regions (ListRegions) Adds the per-team region catalog the console renders as its region picker. The default region is always listed; every other open region is listed only when the team holds its placement grant, so the catalog agrees slug for slug with what a create admits. Schemas are named harness_region / harness_regions_response rather than region, which already names the Droplet region schema; without the prefix the bundler renames them to definitions_region and the generated SDK types read as DefinitionsRegion. Implemented by cthulhu #183673. * agents: document ListRegions under /v2/harness-runtime, and how a slug is used Moves the path and the curl example to /v2/harness-runtime/regions. #1302 moves the documented Harness Runtime surface to that prefix and names this PR; a new route under /v2/agents would conflict with it. Rewrites the descriptions. They said a returned slug "is accepted as the region a session or config is created in", which reads as a placement choice. create_session_request.region says the opposite: the session is always created in the region whose API host served the request, and the body field is only a check against that host. The slug now names the host to call, is_default names the region the region-less host serves, and the operation says what a team outside the regional routing rollout sees. Reported in review by @DO-rrao. --------- Co-authored-by: RohithSangati <73009657+RohithSangati@users.noreply.github.com>
Summary
The Harness Runtime API is now reachable at
/v2/harness-runtime. The edge authorizes the new prefix and rewrites it onto/v2/agents, so no service changed and the responses are identical either way. This moves the documented surface to the new prefix./v2/agentskeeps working for callers on an older client — it is just no longer the documented spelling. Documenting both is not an option: the two spellings would carry duplicateoperationIds, which generated clients cannot express.One exception: a trigger's
webhook_url(and the createLocation) still come back as/v2/agents/triggers/{id}/webhook. That example stays on the spelling the service returns. Both/v2/agents/triggers/{id}/webhookand/v2/harness-runtime/triggers/{id}/webhookare accepted and keep working; callers pastewebhook_urlunchanged. The URL is what gets configured in GitHub, GitLab and Slack.The rename also makes the path match the names already in use elsewhere: the
Harness Runtimetag in this spec,doctl harness-runtime, and theharness-runtimeMCP service./v2/agentswas additionally the wrong noun, since/v2/gen-ai/agentsis a different product and aharness: nonesession has no agent in it at all.What changed
One mechanical prefix swap, 135 occurrences across 69 files, including the routes #1301 added (cancel, image messages, provider connections):
paths:keys inDigitalOcean-public.v2.yamlmodels/definitions.ymldescriptionsagents_list_config_sessions.ymlandagents_port_forward_session.ymlHarness Runtimetag descriptionThe tag description is also rewrapped, because the longer prefix pushed several lines past the wrap the rest of that block uses. No wording changed there.
webhook_config.webhook_urlis not part of that swap. Its example ishttps://api.digitalocean.com/v2/agents/triggers/b1a0.../webhook.Unchanged: every
operationId, tag, parameter and request/response schema. A generated client keeps its method names, and only the URL it builds moves.Client lane
X-Device-UUIDunder either prefix.operations/follow this spec, through the usual clientgen bot, once this merges and publishes.Heads up for the other in-flight agents PRs
#1291 and #1296 both add paths under
/v2/agents. They will conflict here and should land on/v2/harness-runtimeinstead — new Harness Runtime routes should not be added under the old prefix from now on.Test plan
make bundle: bundles clean; the new path keys appear in the bundle.spectral linton the spec and on the bundle: 0 errors, and the same 8 warningsmainalready reports. The one warning in a file this PR touches (agents_port_forward_session.yml, a WebSocket upgrade with only a 101 response) is pre-existing and unrelated.rg '/v2/agents' specification/matches only thewebhook_urlexample and the receive-webhook note that both spellings stay accepted.Made with Cursor