Skip to content

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

Open
Zen-cronic wants to merge 1 commit into
CALLE-AI:mainfrom
Zen-cronic:docs/goal-run-queued-status
Open

Zen-cronic wants to merge 1 commit into
CALLE-AI:mainfrom
Zen-cronic:docs/goal-run-queued-status

Conversation

@Zen-cronic

Copy link
Copy Markdown

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.
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