Durably admit a caller-owned Turn and its 1:1 Run
package main
import ( "fmt" "strings" "net/http" "io")
func main() {
url := "https://api.vampikez.fun/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/turns/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731"
payload := strings.NewReader("{ \"message\": \"Use a sliding window of 100 requests per minute per API key.\", \"replyTo\": { \"interactionId\": \"toolu_01H8sZ4kQm2rVn9pXfB3tGdA\" } }")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>") req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close() body, _ := io.ReadAll(res.Body)
fmt.Println(res) fmt.Println(string(body))
}const url = 'https://api.vampikez.fun/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/turns/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"message":"Use a sliding window of 100 requests per minute per API key.","replyTo":{"interactionId":"toolu_01H8sZ4kQm2rVn9pXfB3tGdA"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://api.vampikez.fun/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/turns/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731 \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "message": "Use a sliding window of 100 requests per minute per API key.", "replyTo": { "interactionId": "toolu_01H8sZ4kQm2rVn9pXfB3tGdA" } }'Returns after the immutable Turn and QUEUED Run commit. Compute provisioning and engine admission happen asynchronously. If the previous Run has ended but its checkpoint is still being sealed, the Turn is accepted immediately and remains QUEUED until that checkpoint is durable. Reply to an open Interaction by setting replyTo.interactionId.
Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.
Example
9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731A UUID you mint and own; it is the idempotency key for creation and the address of every Turn, artifact and publication underneath
A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.
Example
9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731A UUID you mint for this Turn; it is both the idempotency key and the id of the Run it creates
Request Bodyrequired
Section titled “Request Bodyrequired”Body of the idempotent Turn admission. The target agent is snapshotted on the immutable Turn and, when it changes, updates the idle Session in the same transaction. Interaction replies always retain their origin runtime. The same caller-owned Turn id with the same content is a safe retry; the same id with different content is a conflict.
object
The prompt to execute; it becomes this Turn’s immutable input
Model snapshot for this Turn. For WAMP this is a catalog model; runtime-managed agents own their model namespace. Omit to inherit the Session default.
Agent runtime that owns this Turn. Omit to inherit the Session runtime; changing it atomically hands the idle Session to this runtime.
WAMP-native reasoning level; invalid for a runtime-managed agent.
Runtime-owned immutable settings for this Turn; invalid for WAMP’s native loop. A model-setting value the runtime’s observed configCatalog does not offer returns 400 cloud_agent_model_unavailable.
object
Answers one specific open Interaction — the id is rechecked at admission and again at engine dispatch, so a stale prompt in a UI cannot answer a different question
object
Files presented in Sessions this caller may read, by the ids their artifact listing shows. Cloud copies the bytes into this Session before admitting the Turn (at most 64 MiB in all), and the agent finds each one at <workspace>/.wamp/inputs/<turnId>/<name>; small images, PDFs and text are also shown to the model inline. A reference to a file that is not a presented artifact of a readable Session is refused with 400 invalid_request naming its index.
object
Example
{ "message": "Use a sliding window of 100 requests per minute per API key.", "replyTo": { "interactionId": "toolu_01H8sZ4kQm2rVn9pXfB3tGdA" }}Responses
Section titled “ Responses ”Turn admitted or replayed
The 202 result of admitting a Turn: the immutable Turn and its queued Run are already committed to Postgres, while compute provisioning and engine start happen afterwards.
object
The durably admitted Turn, normally still pending dispatch at this point
object
The caller-owned Turn id; the one Run admitted with it carries this exact same value
Session this Turn belongs to
Session-local admission order starting at 0, and the value Turn paging is keyed on
The immutable admitted input — the message plus whatever model, runtime and reply the caller actually requested
object
object
object
Durable hand-off state to the engine: pending before a worker claims it, attempted once delivery started, confirmed when the engine accepted it, rejected when it definitively did not
The single Run this Turn created; its id equals the Turn id
object
A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.
object
A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.
object
object
When admission committed the Turn, which is before any compute necessarily existed
The 1:1 Run created with it, normally still queued
object
Run id, always equal to the id of the Turn that created it
Session this Run belongs to
queued, dispatching and running are in flight, awaiting means the agent is blocked on human input, and completed, failed, cancelled and crashed are terminal
How many times a worker has claimed this Run; recovery after a lost worker increments it instead of creating a second Run
Whether cancellation was durably requested; it stays true after the Run terminates, and it never asserts that an external side effect was undone
Coarse machine code for the most recent failure, retained across retries; absent when nothing has failed. This is the whole declared vocabulary: a failure with no code of its own is recorded as dispatch_failed rather than as an undeclared value. Read status first — this field is present on a queued Run that is still retrying, where it names why the last attempt did not place, and the placement and cancellation codes appear there and never on an event. Treat the set as additive and tolerate a value you do not recognize.
object
When admission committed this Run in queued
Last durable Run state change
When a worker actually began executing; absent while the Run is still queued
When the Run reached a terminal status; absent otherwise
False when this request was an exact idempotent replay and the stored Turn was returned unchanged
Example
{ "turn": { "id": "8f2d5b41-6e0c-47a9-b3d8-51ca9e07f2b6", "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731", "ordinal": 1, "input": { "message": "Use a sliding window of 100 requests per minute per API key.", "model": "claude-opus-5", "runtime": "wamp", "replyTo": { "interactionId": "toolu_01H8sZ4kQm2rVn9pXfB3tGdA" } }, "dispatch": "pending", "run": { "id": "8f2d5b41-6e0c-47a9-b3d8-51ca9e07f2b6" }, "createdAt": "2026-08-12T09:46:12Z" }, "run": { "id": "8f2d5b41-6e0c-47a9-b3d8-51ca9e07f2b6", "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731", "status": "queued", "attempts": 0, "cancellationRequested": false, "createdAt": "2026-08-12T09:46:12Z", "updatedAt": "2026-08-12T09:46:12Z" }, "created": true}Headers
Section titled “Headers”Malformed request
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Returned with invalid_request: one entry per field of the request body or query that was refused. The WAMP Account API sends the same two keys under the same field name, and no others are sent by either.
object
Field path, outermost segment first. An integer segment is an array index.
Short reason the field was refused. Prose for a human to read; branch on the code and the path, never on this.
Returned with invalid_path_parameter: the name of the path segment that is not a valid id, such as sessionId or artifactId
Returned with unsupported_media_type: the Content-Type you sent, echoed back. Omitted when the request carried a body and no Content-Type at all, which is the same refusal. Request bodies are read only under application/json and RFC 6839 application/*+json; anything else is never parsed, so no field of it was ever seen.
Returned with method_not_allowed: the methods this path does answer, the same list as the Allow header on the response. Read the header if you want one code path for every 405 on the API.
The winning approval decision on 409 cloud_interaction_conflict, when an answer exists; absent for a closed or expired request without an answer
object
Example
{ "error": "invalid_request"}No bearer was presented (bearer_credential_required), or the one presented is expired, revoked or for another audience (invalid_or_expired_credential)
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Returned with invalid_request: one entry per field of the request body or query that was refused. The WAMP Account API sends the same two keys under the same field name, and no others are sent by either.
object
Field path, outermost segment first. An integer segment is an array index.
Short reason the field was refused. Prose for a human to read; branch on the code and the path, never on this.
Returned with invalid_path_parameter: the name of the path segment that is not a valid id, such as sessionId or artifactId
Returned with unsupported_media_type: the Content-Type you sent, echoed back. Omitted when the request carried a body and no Content-Type at all, which is the same refusal. Request bodies are read only under application/json and RFC 6839 application/*+json; anything else is never parsed, so no field of it was ever seen.
Returned with method_not_allowed: the methods this path does answer, the same list as the Allow header on the response. Read the header if you want one code path for every 405 on the API.
The winning approval decision on 409 cloud_interaction_conflict, when an answer exists; absent for a closed or expired request without an answer
object
Example
{ "error": "bearer_credential_required"}Live installation, scope or organization policy denies the operation
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Returned with invalid_request: one entry per field of the request body or query that was refused. The WAMP Account API sends the same two keys under the same field name, and no others are sent by either.
object
Field path, outermost segment first. An integer segment is an array index.
Short reason the field was refused. Prose for a human to read; branch on the code and the path, never on this.
Returned with invalid_path_parameter: the name of the path segment that is not a valid id, such as sessionId or artifactId
Returned with unsupported_media_type: the Content-Type you sent, echoed back. Omitted when the request carried a body and no Content-Type at all, which is the same refusal. Request bodies are read only under application/json and RFC 6839 application/*+json; anything else is never parsed, so no field of it was ever seen.
Returned with method_not_allowed: the methods this path does answer, the same list as the Allow header on the response. Read the header if you want one code path for every 405 on the API.
The winning approval decision on 409 cloud_interaction_conflict, when an answer exists; absent for a closed or expired request without an answer
object
Example
{ "error": "insufficient_scope", "requiredScope": "wamp.cloud.sessions:create"}The resource is missing or inaccessible
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Returned with invalid_request: one entry per field of the request body or query that was refused. The WAMP Account API sends the same two keys under the same field name, and no others are sent by either.
object
Field path, outermost segment first. An integer segment is an array index.
Short reason the field was refused. Prose for a human to read; branch on the code and the path, never on this.
Returned with invalid_path_parameter: the name of the path segment that is not a valid id, such as sessionId or artifactId
Returned with unsupported_media_type: the Content-Type you sent, echoed back. Omitted when the request carried a body and no Content-Type at all, which is the same refusal. Request bodies are read only under application/json and RFC 6839 application/*+json; anything else is never parsed, so no field of it was ever seen.
Returned with method_not_allowed: the methods this path does answer, the same list as the Allow header on the response. Read the header if you want one code path for every 405 on the API.
The winning approval decision on 409 cloud_interaction_conflict, when an answer exists; absent for a closed or expired request without an answer
object
Example
{ "error": "cloud_session_not_found"}Idempotency, lifecycle, revision or single-flight conflict
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Returned with invalid_request: one entry per field of the request body or query that was refused. The WAMP Account API sends the same two keys under the same field name, and no others are sent by either.
object
Field path, outermost segment first. An integer segment is an array index.
Short reason the field was refused. Prose for a human to read; branch on the code and the path, never on this.
Returned with invalid_path_parameter: the name of the path segment that is not a valid id, such as sessionId or artifactId
Returned with unsupported_media_type: the Content-Type you sent, echoed back. Omitted when the request carried a body and no Content-Type at all, which is the same refusal. Request bodies are read only under application/json and RFC 6839 application/*+json; anything else is never parsed, so no field of it was ever seen.
Returned with method_not_allowed: the methods this path does answer, the same list as the Allow header on the response. Read the header if you want one code path for every 405 on the API.
The winning approval decision on 409 cloud_interaction_conflict, when an answer exists; absent for a closed or expired request without an answer
object
Example
{ "error": "cloud_session_conflict"}The request body was never read. Either the Content-Type is not a JSON media type — bodies are parsed only under application/json and RFC 6839 application/*+json — or its content encoding or charset was refused. unsupported_media_type echoes the type you sent in mediaType. Malformed JSON under an accepted media type is a different answer: 400 malformed_request_body.
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Returned with invalid_request: one entry per field of the request body or query that was refused. The WAMP Account API sends the same two keys under the same field name, and no others are sent by either.
object
Field path, outermost segment first. An integer segment is an array index.
Short reason the field was refused. Prose for a human to read; branch on the code and the path, never on this.
Returned with invalid_path_parameter: the name of the path segment that is not a valid id, such as sessionId or artifactId
Returned with unsupported_media_type: the Content-Type you sent, echoed back. Omitted when the request carried a body and no Content-Type at all, which is the same refusal. Request bodies are read only under application/json and RFC 6839 application/*+json; anything else is never parsed, so no field of it was ever seen.
Returned with method_not_allowed: the methods this path does answer, the same list as the Allow header on the response. Read the header if you want one code path for every 405 on the API.
The winning approval decision on 409 cloud_interaction_conflict, when an answer exists; absent for a closed or expired request without an answer
object
Example
{ "error": "unsupported_media_type", "mediaType": "application/x-www-form-urlencoded"}The pre-authentication edge budget or durable human-membership/App-installation budget is exhausted
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Returned with invalid_request: one entry per field of the request body or query that was refused. The WAMP Account API sends the same two keys under the same field name, and no others are sent by either.
object
Field path, outermost segment first. An integer segment is an array index.
Short reason the field was refused. Prose for a human to read; branch on the code and the path, never on this.
Returned with invalid_path_parameter: the name of the path segment that is not a valid id, such as sessionId or artifactId
Returned with unsupported_media_type: the Content-Type you sent, echoed back. Omitted when the request carried a body and no Content-Type at all, which is the same refusal. Request bodies are read only under application/json and RFC 6839 application/*+json; anything else is never parsed, so no field of it was ever seen.
Returned with method_not_allowed: the methods this path does answer, the same list as the Allow header on the response. Read the header if you want one code path for every 405 on the API.
The winning approval decision on 409 cloud_interaction_conflict, when an answer exists; absent for a closed or expired request without an answer
object
Example
{ "error": "cloud_rate_limit_exceeded", "retryAfterSeconds": 3}Headers
Section titled “Headers”IETF HTTPAPI structured quota policy
IETF HTTPAPI structured current service limit
The request was accepted and something on our side failed while answering it. Nothing about the request needs to change; the same call may succeed on retry. Retry cautiously, with backoff — a non-idempotent command may have taken effect before the fault.
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Returned with invalid_request: one entry per field of the request body or query that was refused. The WAMP Account API sends the same two keys under the same field name, and no others are sent by either.
object
Field path, outermost segment first. An integer segment is an array index.
Short reason the field was refused. Prose for a human to read; branch on the code and the path, never on this.
Returned with invalid_path_parameter: the name of the path segment that is not a valid id, such as sessionId or artifactId
Returned with unsupported_media_type: the Content-Type you sent, echoed back. Omitted when the request carried a body and no Content-Type at all, which is the same refusal. Request bodies are read only under application/json and RFC 6839 application/*+json; anything else is never parsed, so no field of it was ever seen.
Returned with method_not_allowed: the methods this path does answer, the same list as the Allow header on the response. Read the header if you want one code path for every 405 on the API.
The winning approval decision on 409 cloud_interaction_conflict, when an answer exists; absent for a closed or expired request without an answer
object
Example
{ "error": "internal_error"}A retryable condition: a workspace, runtime or provider that is not available yet, or service_unavailable while the service restarts for a release or its database cannot serve the request in time. Retry after the Retry-After this response carries.
Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.
object
Stable machine code
The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request
Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value
Returned with invalid_request: one entry per field of the request body or query that was refused. The WAMP Account API sends the same two keys under the same field name, and no others are sent by either.
object
Field path, outermost segment first. An integer segment is an array index.
Short reason the field was refused. Prose for a human to read; branch on the code and the path, never on this.
Returned with invalid_path_parameter: the name of the path segment that is not a valid id, such as sessionId or artifactId
Returned with unsupported_media_type: the Content-Type you sent, echoed back. Omitted when the request carried a body and no Content-Type at all, which is the same refusal. Request bodies are read only under application/json and RFC 6839 application/*+json; anything else is never parsed, so no field of it was ever seen.
Returned with method_not_allowed: the methods this path does answer, the same list as the Allow header on the response. Read the header if you want one code path for every 405 on the API.
The winning approval decision on 409 cloud_interaction_conflict, when an answer exists; absent for a closed or expired request without an answer
object
Example
{ "error": "cloud_workspace_unavailable"}