Create session
Viewing v2— current version
curl --request POST \ --url https://api.app.layer.ai/api/v2/workspaces/:workspace_id/sessions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "<string>"}'import requests
url = "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/sessions"
payload = { "name": "<string>" }headers = { "Authorization": "Bearer <token>", "Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.json())const url = 'https://api.app.layer.ai/api/v2/workspaces/:workspace_id/sessions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"<string>"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}package main
import ( "fmt" "strings" "net/http" "io")
func main() {
url := "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/sessions"
payload := strings.NewReader("{\n \"name\": \"<string>\"\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(res) fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [ CURLOPT_URL => "https://api.app.layer.ai/api/v2/workspaces/:workspace_id/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([ 'name' => '<string>' ]), 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;}OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");RequestBody body = RequestBody.create(mediaType, "{\n \"name\": \"<string>\"\n}");Request request = new Request.Builder() .url("https://api.app.layer.ai/api/v2/workspaces/:workspace_id/sessions") .post(body) .addHeader("Authorization", "Bearer <token>") .addHeader("Content-Type", "application/json") .build();
Response response = client.newCall(request).execute();require 'uri'require 'net/http'
url = URI("https://api.app.layer.ai/api/v2/workspaces/:workspace_id/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 \"name\": \"<string>\"\n}"
response = http.request(request)puts response.read_bodyvar client = new RestClient("https://api.app.layer.ai/api/v2/workspaces/:workspace_id/sessions");var request = new RestRequest("", Method.Post);request.AddHeader("Authorization", "Bearer <token>");request.AddHeader("Content-Type", "application/json");request.AddParameter("application/json", "{\n \"name\": \"<string>\"\n}", ParameterType.RequestBody);var response = client.Execute(request);New in v2. This endpoint has no v1 equivalent.
Create an empty session. Names need not be unique: a client that means to resume a session should keep its session_id rather than look it up by name.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Id of the workspace that owns the resource.
Id of the workspace that owns the resource.
Header Parameters
Section titled “Header Parameters”Opaque key making a retry of this request return the first result. A 2xx response is replayed for 24 hours with Idempotent-Replayed: true. A 4xx releases the key. A 5xx, or a request still running, holds the key for 120 seconds, during which a retry gets 409; after that a retry executes again. The key covers the method, path, query, and byte-identical body it was first used with; reusing it for a different request is rejected with 422. Protection is best effort: if the key store is unavailable, or a record is lost early, a retry can execute again even after an earlier 409. See the Idempotency section of the API description.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The session’s display name.
Examplegenerated
{ "name": "example"}Responses
Section titled “Responses”Successful Response
object
The session’s unique identifier.
The session’s display name.
The project the session is filed under, if any.
When the session was created.
When anyone last worked in the session, or null if nobody has yet.
Examplegenerated
{ "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "name": "example", "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "created_at": "2026-04-15T12:00:00Z", "last_interacted_at": "2026-04-15T12:00:00Z"}Unauthenticated — missing or invalid Bearer token.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Forbidden — insufficient permissions, or the access token lacks the scope the operation requires.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Resource not found.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}The outcome of the request with this Idempotency-Key is not known yet: it is still running, or it failed without a stored response. Retry after the number of seconds in Retry-After.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Invalid input parameters, or an Idempotency-Key reused for a different request.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Rate limited — retry after the number of seconds in Retry-After.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}Internal server error.
object
Example
{ "type": "https://api.layer.ai/errors/ERROR_CODE", "title": "Error Title", "status": 400, "detail": "Human-readable description."}