Capture Session - Agnost AI

Capture session

curl --request POST \
  --url https://api.agnost.ai/api/v1/capture-session \
  --header 'Content-Type: application/json' \
  --header 'x-org-id: <x-org-id>' \
  --data '
{
  "session_id": "a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731",
  "user_data": {
    "user_id": "user-anon-002",
    "email": "[email protected]",
    "user_plan": "pro"
  },
  "metadata": {
    "language": "hi-IN"
  },
  "timestamp": 1714867200000,
  "client_config": "client-segment-001"
}
'

import requests

url = "https://api.agnost.ai/api/v1/capture-session"

payload = {
    "session_id": "a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731",
    "user_data": {
        "user_id": "user-anon-002",
        "email": "[email protected]",
        "user_plan": "pro"
    },
    "metadata": { "language": "hi-IN" },
    "timestamp": 1714867200000,
    "client_config": "client-segment-001"
}
headers = {
    "x-org-id": "<x-org-id>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-org-id': '<x-org-id>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    session_id: 'a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731',
    user_data: {user_id: 'user-anon-002', email: '[email protected]', user_plan: 'pro'},
    metadata: {language: 'hi-IN'},
    timestamp: 1714867200000,
    client_config: 'client-segment-001'
  })
};

fetch('https://api.agnost.ai/api/v1/capture-session', 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.agnost.ai/api/v1/capture-session",
  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([
    'session_id' => 'a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731',
    'user_data' => [
        'user_id' => 'user-anon-002',
        'email' => '[email protected]',
        'user_plan' => 'pro'
    ],
    'metadata' => [
        'language' => 'hi-IN'
    ],
    'timestamp' => 1714867200000,
    'client_config' => 'client-segment-001'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-org-id: <x-org-id>"
  ],
]);

$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.agnost.ai/api/v1/capture-session"

	payload := strings.NewReader("{\n  \"session_id\": \"a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731\",\n  \"user_data\": {\n    \"user_id\": \"user-anon-002\",\n    \"email\": \"[email protected]\",\n    \"user_plan\": \"pro\"\n  },\n  \"metadata\": {\n    \"language\": \"hi-IN\"\n  },\n  \"timestamp\": 1714867200000,\n  \"client_config\": \"client-segment-001\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-org-id", "<x-org-id>")
	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.agnost.ai/api/v1/capture-session")
  .header("x-org-id", "<x-org-id>")
  .header("Content-Type", "application/json")
  .body("{\n  \"session_id\": \"a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731\",\n  \"user_data\": {\n    \"user_id\": \"user-anon-002\",\n    \"email\": \"[email protected]\",\n    \"user_plan\": \"pro\"\n  },\n  \"metadata\": {\n    \"language\": \"hi-IN\"\n  },\n  \"timestamp\": 1714867200000,\n  \"client_config\": \"client-segment-001\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agnost.ai/api/v1/capture-session")

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

request = Net::HTTP::Post.new(url)
request["x-org-id"] = '<x-org-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"session_id\": \"a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731\",\n  \"user_data\": {\n    \"user_id\": \"user-anon-002\",\n    \"email\": \"[email protected]\",\n    \"user_plan\": \"pro\"\n  },\n  \"metadata\": {\n    \"language\": \"hi-IN\"\n  },\n  \"timestamp\": 1714867200000,\n  \"client_config\": \"client-segment-001\"\n}"

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

{
  "session_id": "<string>"
}

{
  "error": "Invalid request body"
}

POST

api

capture-session

Capture session

curl --request POST \
  --url https://api.agnost.ai/api/v1/capture-session \
  --header 'Content-Type: application/json' \
  --header 'x-org-id: <x-org-id>' \
  --data '
{
  "session_id": "a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731",
  "user_data": {
    "user_id": "user-anon-002",
    "email": "[email protected]",
    "user_plan": "pro"
  },
  "metadata": {
    "language": "hi-IN"
  },
  "timestamp": 1714867200000,
  "client_config": "client-segment-001"
}
'

import requests

url = "https://api.agnost.ai/api/v1/capture-session"

payload = {
    "session_id": "a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731",
    "user_data": {
        "user_id": "user-anon-002",
        "email": "[email protected]",
        "user_plan": "pro"
    },
    "metadata": { "language": "hi-IN" },
    "timestamp": 1714867200000,
    "client_config": "client-segment-001"
}
headers = {
    "x-org-id": "<x-org-id>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-org-id': '<x-org-id>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    session_id: 'a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731',
    user_data: {user_id: 'user-anon-002', email: '[email protected]', user_plan: 'pro'},
    metadata: {language: 'hi-IN'},
    timestamp: 1714867200000,
    client_config: 'client-segment-001'
  })
};

fetch('https://api.agnost.ai/api/v1/capture-session', 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.agnost.ai/api/v1/capture-session",
  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([
    'session_id' => 'a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731',
    'user_data' => [
        'user_id' => 'user-anon-002',
        'email' => '[email protected]',
        'user_plan' => 'pro'
    ],
    'metadata' => [
        'language' => 'hi-IN'
    ],
    'timestamp' => 1714867200000,
    'client_config' => 'client-segment-001'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-org-id: <x-org-id>"
  ],
]);

$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.agnost.ai/api/v1/capture-session"

	payload := strings.NewReader("{\n  \"session_id\": \"a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731\",\n  \"user_data\": {\n    \"user_id\": \"user-anon-002\",\n    \"email\": \"[email protected]\",\n    \"user_plan\": \"pro\"\n  },\n  \"metadata\": {\n    \"language\": \"hi-IN\"\n  },\n  \"timestamp\": 1714867200000,\n  \"client_config\": \"client-segment-001\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-org-id", "<x-org-id>")
	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.agnost.ai/api/v1/capture-session")
  .header("x-org-id", "<x-org-id>")
  .header("Content-Type", "application/json")
  .body("{\n  \"session_id\": \"a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731\",\n  \"user_data\": {\n    \"user_id\": \"user-anon-002\",\n    \"email\": \"[email protected]\",\n    \"user_plan\": \"pro\"\n  },\n  \"metadata\": {\n    \"language\": \"hi-IN\"\n  },\n  \"timestamp\": 1714867200000,\n  \"client_config\": \"client-segment-001\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agnost.ai/api/v1/capture-session")

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

request = Net::HTTP::Post.new(url)
request["x-org-id"] = '<x-org-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"session_id\": \"a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731\",\n  \"user_data\": {\n    \"user_id\": \"user-anon-002\",\n    \"email\": \"[email protected]\",\n    \"user_plan\": \"pro\"\n  },\n  \"metadata\": {\n    \"language\": \"hi-IN\"\n  },\n  \"timestamp\": 1714867200000,\n  \"client_config\": \"client-segment-001\"\n}"

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

{
  "session_id": "<string>"
}

{
  "error": "Invalid request body"
}

Call once per conversation. Reuse session_id on every event that follows.

Body

Field	Type	Required	Description
`session_id`	`string` (UUID)	Required	Session UUID. Reuse on every event in this conversation.
`user_data`	`object`	Required	End-user identity. Must contain `user_id`. Prefer a stable pseudonymous ID; avoid raw email, name, phone, or other personal data unless explicitly approved.
`metadata`	`object`	Optional	Free-form session metadata. Prefer allowlisted operational fields; do not send secrets or sensitive personal data.
`timestamp`	`integer` (ms)	Optional	Unix time in ms when the session began. Defaults to server time.
`client_config`	`string`	Optional	Free-form client/SDK label.

For production data-handling guidance, see Data Governance.

Verify

After creating a session and sending at least one event, open Raw logs in Agnost and confirm the session_id appears on the event.

Troubleshooting

session_id must be a UUID.
user_data.user_id is required.
Reuse the same session_id for every event in the conversation.

Headers

x-org-id

string

required

Your organization ID (UUID, case-insensitive).

Example:

"<org-id>"

Body

application/json

session_id

string<uuid>

required

Session UUID. Reuse on every event in this conversation.

Example:

"a3f9c182-7d4e-4b6a-9e21-c5d8f0b4e731"

user_data

object

required

End-user identity. user_id is required; other traits are supported for analytics. The example shows shape, but production integrations should prefer a stable pseudonymous ID and avoid raw email, name, phone, or other personal data unless explicitly approved.

Show child attributes

Example:

{
  "user_id": "user-anon-002",
  "email": "[email protected]",
  "user_plan": "pro"
}

metadata

object

Free-form session metadata. Prefer allowlisted operational fields; do not send secrets or sensitive personal data.

Show child attributes

Example:

{ "language": "hi-IN" }

timestamp

integer<int64>

Unix time in ms when the session began. Defaults to server time.

Example:

1714867200000

client_config

string

Free-form client/SDK label.

Example:

"client-segment-001"

Response

Session created

session_id

string

SDKs Capture Event

​Body

​Verify

​Troubleshooting

Headers

Body

Response

Body

Verify

Troubleshooting