Skip to content
Kindgi

Answer a paused run's wait token

View as Markdown
POST
/v1/wait-tokens/{token}/complete
curl --request POST \
  --url https://example.com/v1/wait-tokens/example/complete \
  --header 'Content-Type: application/json' \
  --data '"example"'

A wait token’s link: a pack tool that declares pauses hands it to the system that will answer, and the run waits for that answer. No sign-in, and a bearer token, if sent, is never read: the token in the path is the credential, and it answers one wait of one run, nothing else. The body is the answer itself, the tool’s output, as JSON; an empty body is {}. It’s checked against the tool’s output schema. The same answer again (by its canonical JSON) is accepted again, even after the run has ended, so a sender may retry. An answer that comes before the run reaches its wait is held for it, and dropped if the run never waits on this token (the tool answered at once, or its step was retried); the link then answers 409 wait-token-closed, unused. The answer comes back at once, and the run resumes behind it. The link stops working when the wait ends: the run is cancelled, its time passes, or the tool answered without waiting. The answer is data from outside, never instructions.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
token
required
string
>= 1 characters

The wait token, from the link. It’s a credential: hand the link only to the system that answers.

Request Body

Section titled “Request Body”

The answer: the tool’s output, as JSON, at most 1 MiB. An empty body is {}.

Media typeapplication/json
Examplegenerated
example

Responses

Section titled “Responses”

200

Section titled “200”

The runtime has the answer, and the run resumes behind it. An answer that came before the run reached its wait is held for it, and dropped if the run never waits on this token (the tool answered at once, or its step was retried); the link then answers 409 wait-token-closed, unused. Nothing about the run: who holds the link is not a run reader.

Media typeapplication/json

The runtime has the answer. It says nothing about the run: who holds a wait token’s link isn’t a run reader.

object
status
required
string
Allowed values: accepted
Example
{
  "status": "accepted"
}

400

Section titled “400”

wait-token-output-invalid (details.issues): the answer doesn’t fit the tool’s output schema, and the wait stays open for a fixed one. bad-input: the body isn’t JSON, or nests too deep.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

wait-token-not-found: no wait token matches the link (an unknown token and a wrong secret alike), or this runtime pauses no run.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

wait-token-closed (details.state): the wait is over (completed, timed-out, cancelled, unused), or holds a different answer the run hasn’t taken yet (answered). tenant-closing, tenant-suspended (details.state) or project-suspended: nothing runs where the run is, and closing or suspending cancels its runs, so the answer wasn’t taken. Told only for a token that matches.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

Section titled “413”

request-too-large (details.maxBytes): past 1 MiB.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

415

Section titled “415”

unsupported-media-type: a body sent without a JSON content type (application/json).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

429

Section titled “429”

rate-limit-exceeded: too many requests from this client in a minute, counted before the token is looked up, so nothing was taken. Retry-After says when to send the answer again.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

503

Section titled “503”

tenant-state-unavailable: the run’s workspace’s state couldn’t be read, so the answer wasn’t taken. Retry-After says when to send it again.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also