curl --request POST \
--url https://api.deck.co/v2/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"source_id": "src_AbC123xYz456"
}
'import requests
url = "https://api.deck.co/v2/sessions"
payload = { "source_id": "src_AbC123xYz456" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({source_id: 'src_AbC123xYz456'})
};
fetch('https://api.deck.co/v2/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.deck.co/v2/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([
'source_id' => 'src_AbC123xYz456'
]),
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.deck.co/v2/sessions"
payload := strings.NewReader("{\n \"source_id\": \"src_AbC123xYz456\"\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.deck.co/v2/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"source_id\": \"src_AbC123xYz456\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.deck.co/v2/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"source_id\": \"src_AbC123xYz456\"\n}"
response = http.request(request)
puts response.read_body{
"id": "sess_AbC123xYz456",
"object": "<string>",
"status": "<string>",
"runtime_ms": 123,
"task_runs": [
{
"id": "<string>",
"task_id": "<string>",
"agent_id": "<string>",
"credential_id": "<string>"
}
],
"created_at": "2026-08-24T12:00:00Z",
"updated_at": "2026-08-24T12:00:00Z",
"request_id": "<string>",
"source_id": "src_AbC123xYz456"
}{
"errors": {},
"type": "<string>",
"title": "<string>",
"status": 123,
"traceId": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}Start a session
Starts a new isolated compute session for executing tasks. Pass an optional source_id to prepare the session: the agent opens that source’s login page ahead of the first run, so an auth run on this session starts a few seconds ahead. A component token may hold one active session at a time.
curl --request POST \
--url https://api.deck.co/v2/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"source_id": "src_AbC123xYz456"
}
'import requests
url = "https://api.deck.co/v2/sessions"
payload = { "source_id": "src_AbC123xYz456" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({source_id: 'src_AbC123xYz456'})
};
fetch('https://api.deck.co/v2/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.deck.co/v2/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([
'source_id' => 'src_AbC123xYz456'
]),
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.deck.co/v2/sessions"
payload := strings.NewReader("{\n \"source_id\": \"src_AbC123xYz456\"\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.deck.co/v2/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"source_id\": \"src_AbC123xYz456\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.deck.co/v2/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"source_id\": \"src_AbC123xYz456\"\n}"
response = http.request(request)
puts response.read_body{
"id": "sess_AbC123xYz456",
"object": "<string>",
"status": "<string>",
"runtime_ms": 123,
"task_runs": [
{
"id": "<string>",
"task_id": "<string>",
"agent_id": "<string>",
"credential_id": "<string>"
}
],
"created_at": "2026-08-24T12:00:00Z",
"updated_at": "2026-08-24T12:00:00Z",
"request_id": "<string>",
"source_id": "src_AbC123xYz456"
}{
"errors": {},
"type": "<string>",
"title": "<string>",
"status": 123,
"traceId": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}{
"errors": [
{
"type": "<string>",
"code": "<string>",
"message": "<string>",
"field": "<string>"
}
],
"request_id": "<string>"
}Headers
Optional key that makes the request idempotent. Retrying with the same key returns the original response instead of repeating the operation; keys expire after 24 hours. Any string up to 256 characters. See Idempotency.
256"550e8400-e29b-41d4-a716-446655440000"
Body
Request body for starting a session. Every field is optional; an empty body starts a plain session.
The source to prepare the session for. The agent opens that source's login page ahead of the first run, so an auth run on this session starts a few seconds ahead. A hint for what the session does next, not a restriction on it: a task or workflow run on the session can target any source, and the session's network path is fixed by the first run that uses it rather than by this field. An unknown source returns 404. Prefixed with src_.
^src_"src_AbC123xYz456"
Response
Created
A session object representing an isolated compute session for executing tasks.
Was this page helpful?