Workspaces
Create a session in a workspace
Requires sessions:write on a workspace the key’s account owns. A key may create chat and agent_test sessions; api_trigger is a 403. The key is recorded as the session’s initiator (serialized type: "api_key"), and a chat’s agent begins executing initial_prompt immediately.
POST
/
workspaces
/
{workspace_id_or_name}
/
sessions
Create a session in a workspace
curl --request POST \
--url https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "<string>",
"initial_prompt": "<string>",
"agent_version_id": "<string>",
"context_override_id": "<string>"
}
'import requests
url = "https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions"
payload = {
"agent_id": "<string>",
"initial_prompt": "<string>",
"agent_version_id": "<string>",
"context_override_id": "<string>"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '<string>',
initial_prompt: '<string>',
agent_version_id: '<string>',
context_override_id: '<string>'
})
};
fetch('https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions', 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.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => '<string>',
'initial_prompt' => '<string>',
'agent_version_id' => '<string>',
'context_override_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"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.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions"
payload := strings.NewReader("{\n \"agent_id\": \"<string>\",\n \"initial_prompt\": \"<string>\",\n \"agent_version_id\": \"<string>\",\n \"context_override_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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.post("https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": \"<string>\",\n \"initial_prompt\": \"<string>\",\n \"agent_version_id\": \"<string>\",\n \"context_override_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"<string>\",\n \"initial_prompt\": \"<string>\",\n \"agent_version_id\": \"<string>\",\n \"context_override_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"test_type": "MANUAL",
"version_override_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"context_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"context_override_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"interrupted_at": "2023-11-07T05:31:56Z",
"interrupted_by_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"seed_context": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}Authorizations
apiKeybearerApiKeyoauth2
API key: key id as the username, secret as the password. An account API key carries the same scopes as an OAuth token and is checked against the scopes listed under oauth2 on each operation. A trigger API key is limited to its trigger's workspace and reaches only the session operations that list this scheme alongside the oauth2 scopes.
Path Parameters
Body
application/json
chat holds a conversation with agent_id, starting from initial_prompt. agent_test runs one agent version, given by agent_version_id.
Available options:
chat, agent_test For chat: the agent to converse with, by id or name.
For chat, required: the first message.
For agent_test, required: the agent version to run, draft or published.
For agent_test: a context version to run with instead of the active one.
Response
The created session
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
Who started this agent test session: a user, or an account API key testing from CI.
Eval trials run as agent-test sessions; this separates them from sessions a person started from the agent editor.
Available options:
MANUAL, EVAL The specific agent version being tested in this session.
The workspace this session belongs to.
The context used in this session, if available.
Optional context override for testing purposes.
Timestamp when this session was interrupted by a user. If set, no new messages can be sent and tasks cannot be executed.
User who interrupted this session.
Optional hidden pre-seed text for this session only, prepended to the agent's context on the first turn (e.g. the onboarding handoff tour transcript). Not a workspace context.
Maximum string length:
262144⌘I
Create a session in a workspace
curl --request POST \
--url https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "<string>",
"initial_prompt": "<string>",
"agent_version_id": "<string>",
"context_override_id": "<string>"
}
'import requests
url = "https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions"
payload = {
"agent_id": "<string>",
"initial_prompt": "<string>",
"agent_version_id": "<string>",
"context_override_id": "<string>"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '<string>',
initial_prompt: '<string>',
agent_version_id: '<string>',
context_override_id: '<string>'
})
};
fetch('https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions', 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.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => '<string>',
'initial_prompt' => '<string>',
'agent_version_id' => '<string>',
'context_override_id' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"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.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions"
payload := strings.NewReader("{\n \"agent_id\": \"<string>\",\n \"initial_prompt\": \"<string>\",\n \"agent_version_id\": \"<string>\",\n \"context_override_id\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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.post("https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": \"<string>\",\n \"initial_prompt\": \"<string>\",\n \"agent_version_id\": \"<string>\",\n \"context_override_id\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.guild.ai/v1/workspaces/{workspace_id_or_name}/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"<string>\",\n \"initial_prompt\": \"<string>\",\n \"agent_version_id\": \"<string>\",\n \"context_override_id\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"initiator_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"test_type": "MANUAL",
"version_override_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"context_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"context_override_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"interrupted_at": "2023-11-07T05:31:56Z",
"interrupted_by_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"seed_context": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}{
"error": "<string>",
"message": "<string>"
}