Skip to content

docs: show queued status in the Goal Run creation example - #56

Merged
JJasonSun merged 1 commit into
CALLE-AI:mainfrom
Zen-cronic:docs/goal-run-queued-status
Sep 22, 2026
Merged

JJasonSun merged 1 commit into
CALLE-AI:mainfrom
Zen-cronic:docs/goal-run-queued-status

Conversation

@Zen-cronic

Copy link
Copy Markdown
Contributor

What

The Goal Run Create (POST /v1/goals/{goal_id}/runs) 201 example in content/guides/goal-runs.mdx shows "status": "in_progress" for a run that has just been accepted and not yet dialed ("call_id": null, "result": null, "completed_at": null).

The OpenAPI contract documents the same response with a different status. openapi/calle.openapi.yamlacceptedDeliveryConfirmation is the identical object (id: rgrp_delivery_ord_8472, run_id: run_delivery_ord_8472, call_id: null) and shows:

summary: Delivery confirmation accepted and awaiting execution.
status: queued

The GoalRunStatus enum lists queued and in_progress as the two non-terminal states, with queued first, and the guide's own prose just above the example says a 201 "does not mean the provider accepted the call, the recipient answered, or the structured result is ready." So a freshly-accepted, not-yet-executed run is queued; the create example is the only place that says in_progress, which disagrees with the spec it documents.

Change

One token, content/guides/goal-runs.mdx:

   "call_id": null,
-  "status": "in_progress",
+  "status": "queued",
   "run_spec": {

Found while wiring a live integration against the Goal Runs API — a reader who takes the create example at face value expects in_progress on a 201, which the API doesn't return. Happy to close this if in_progress is intended here instead; in that case the OpenAPI example and the enum ordering are probably the things to align.

The 201 create example returns a run that is accepted but not yet dialed
(call_id: null); per the OpenAPI acceptedDeliveryConfirmation example and the
GoalRunStatus enum, that state is queued, not in_progress.

@JJasonSun JJasonSun left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Reviewed commit 22e0730. The example now matches the current OpenAPI acceptedDeliveryConfirmation response (queued). This is a focused documentation correction; it does not imply that every 201 response, including an idempotent replay, must be queued.

Validated the proposed merge with current main: pnpm run validate passed (13 deployment tests and 22 browser tests). Also verified that the rendered Goal Run creation example shows queued. No blocking findings.

@JJasonSun
JJasonSun merged commit e901814 into CALLE-AI:main Sep 22, 2026
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.

2 participants