Update a session

curl --request PATCH \
  --url https://api.{domain}/v1/sessions/{session_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Nightly report",
  "metadata": {
    "run": "42"
  }
}
'

import requests

url = "https://api.{domain}/v1/sessions/{session_id}"

payload = {
    "title": "Nightly report",
    "metadata": { "run": "42" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({title: 'Nightly report', metadata: {run: '42'}})
};

fetch('https://api.{domain}/v1/sessions/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.{domain}/v1/sessions/{session_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Nightly report',
    'metadata' => [
        'run' => '42'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.{domain}/v1/sessions/{session_id}"

	payload := strings.NewReader("{\n  \"title\": \"Nightly report\",\n  \"metadata\": {\n    \"run\": \"42\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", 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(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.{domain}/v1/sessions/{session_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Nightly report\",\n  \"metadata\": {\n    \"run\": \"42\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.{domain}/v1/sessions/{session_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Nightly report\",\n  \"metadata\": {\n    \"run\": \"42\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "object": "session",
  "id": "<string>",
  "status": "idle",
  "created_at": 123,
  "updated_at": 123,
  "agent": {
    "id": "<string>",
    "model": "<string>",
    "model_credential_id": "<string>",
    "approval_mode": "<string>",
    "instructions": "<string>",
    "permission_rules": [
      {}
    ],
    "tools": [
      {}
    ]
  },
  "environment": {
    "type": "sandbox",
    "state": "unknown",
    "workspace_directory": "<string>",
    "repo": {
      "full_name": "<string>",
      "branch": "<string>",
      "clone_error": "<string>"
    }
  },
  "preview": {
    "url": "<string>",
    "port": 123,
    "published_url": "<string>"
  },
  "title": "<string>",
  "source": "api",
  "created_by_token": "<string>",
  "required_actions": [
    {
      "type": "function_call",
      "turn_id": "<string>",
      "call_id": "<string>",
      "name": "<string>",
      "arguments": "<unknown>",
      "created_at": 123,
      "expires_at": 123
    }
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

PATCH

sessions

{session_id}

Update a session

curl --request PATCH \
  --url https://api.{domain}/v1/sessions/{session_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Nightly report",
  "metadata": {
    "run": "42"
  }
}
'

import requests

url = "https://api.{domain}/v1/sessions/{session_id}"

payload = {
    "title": "Nightly report",
    "metadata": { "run": "42" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({title: 'Nightly report', metadata: {run: '42'}})
};

fetch('https://api.{domain}/v1/sessions/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.{domain}/v1/sessions/{session_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Nightly report',
    'metadata' => [
        'run' => '42'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.{domain}/v1/sessions/{session_id}"

	payload := strings.NewReader("{\n  \"title\": \"Nightly report\",\n  \"metadata\": {\n    \"run\": \"42\"\n  }\n}")

	req, _ := http.NewRequest("PATCH", 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(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.{domain}/v1/sessions/{session_id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Nightly report\",\n  \"metadata\": {\n    \"run\": \"42\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.{domain}/v1/sessions/{session_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Nightly report\",\n  \"metadata\": {\n    \"run\": \"42\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "object": "session",
  "id": "<string>",
  "status": "idle",
  "created_at": 123,
  "updated_at": 123,
  "agent": {
    "id": "<string>",
    "model": "<string>",
    "model_credential_id": "<string>",
    "approval_mode": "<string>",
    "instructions": "<string>",
    "permission_rules": [
      {}
    ],
    "tools": [
      {}
    ]
  },
  "environment": {
    "type": "sandbox",
    "state": "unknown",
    "workspace_directory": "<string>",
    "repo": {
      "full_name": "<string>",
      "branch": "<string>",
      "clone_error": "<string>"
    }
  },
  "preview": {
    "url": "<string>",
    "port": 123,
    "published_url": "<string>"
  },
  "title": "<string>",
  "source": "api",
  "created_by_token": "<string>",
  "required_actions": [
    {
      "type": "function_call",
      "turn_id": "<string>",
      "call_id": "<string>",
      "name": "<string>",
      "arguments": "<unknown>",
      "created_at": 123,
      "expires_at": 123
    }
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A gbr_pat_ access token. Scopes are recorded on the token when it is minted.

Headers

Idempotency-Key

string

Retrying with the same key replays the first answer instead of acting again.

Maximum string length: 255

Body

application/json

Only the fields present are changed.

title

string | null

null clears it.

metadata

object | null

null clears every label.

Show child attributes

agent

object

Change what runs, mid-session. The workspace and the transcript are kept either way.

Show child attributes

Response

Change a session: title, metadata, instructions, or its safety settings.

object

string

required

Always session. Names the shape, so a value can be identified without knowing which call returned it.

Allowed value: "session"

string

required

Ours, not yours. Use metadata to carry your own identifier.

status

enum<string>

required

idle accepts input. working is running a turn. requires_action is waiting on you — see required_actions. failed is the last turn's outcome, not a dead session.

Available options:

idle,

working,

requires_action,

failed

created_at

integer

required

Unix milliseconds.

updated_at

integer

required

Unix milliseconds. Moves on any change, including the workspace waking.

agent

object

required

What is running, and how freely.

Show child attributes

environment

object

required

The workspace: its state, where the agent works, and the repository bound to it.

Show child attributes

preview

object

required

Addresses for whatever the agent is serving. See preview.md.

Show child attributes

title

string | null

A label for people. Set it yourself; nothing derives one.

source

enum<string> | null

Which door created this session. Null on sessions predating the field.

Available options:

api,

console,

cli,

null

created_by_token

string | null

The id of the access token that created it — never its secret.

required_actions

object[]

Everything the session is waiting on you for. Authoritative — not a replay of events, so a caller that restarted gets the same complete answer.

Show child attributes

Start here

Running a session

Guides

Client libraries

When things go wrong

API reference

About this API

Endpoints

Update a session

Authorizations

Headers

Body

Response