Interactive Sessions: API Reference

1curl -X POST https://agent-session-api.xema.dev/sessions \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "agentRef": "engineering-assistant@3",
6    "title": "Refactor auth module",
7    "repositoryId": "repo-123",
8    "branchStrategy": "auto_create",
9    "budgetLimit": 200000
10  }'

1{
2  "id": "clxxxxxxxxxxxxxxxxxx",
3  "orgId": "org-123",
4  "projectId": "proj-456",
5  "title": "Refactor auth module",
6  "status": "creating",
7  "agentSlug": "engineering",
8  "modelId": "anthropic/claude-sonnet-4-20250514",
9  "tokenUsage": null,
10  "budgetLimit": 200000,
11  "branchName": null,
12  "branchStrategy": "auto_create",
13  "repositoryId": "repo-123",
14  "pipelineRunId": null,
15  "parentSessionId": null,
16  "prUrl": null,
17  "failureReason": null,
18  "provisioningPhase": "queued",
19  "createdAt": "2026-04-27T10:30:00Z",
20  "lastActivityAt": "2026-04-27T10:30:00Z"
21}

1curl "https://agent-session-api.xema.dev/sessions?status=active" \
2  -H "Authorization: Bearer $TOKEN"

1{
2  "paused": true
3}

1{
2  "resumed": true
3}

1{
2  "data": [
3    {
4      "id": "thr_main",
5      "sessionId": "cl123",
6      "title": "Main",
7      "status": "active",
8      "turnState": "idle",
9      "agentSlug": null,
10      "createdAt": "2026-04-27T10:30:00Z",
11      "lastActivityAt": "2026-04-27T10:34:12Z"
12    }
13  ]
14}

1curl -X POST \
2  https://agent-session-api.xema.dev/sessions/cl123/threads/thr_main/messages \
3  -H "Authorization: Bearer $TOKEN" \
4  -H "Content-Type: application/json" \
5  -H "Accept: text/event-stream" \
6  -H "Idempotency-Key: $(uuidgen)" \
7  -d '{"content": "Review the authentication module and suggest improvements."}'

1event: text_delta
2data: {"delta": "Looking at the authentication module...", "sessionId": "cl123", "threadId": "thr_main"}
3
4event: thinking
5data: {"delta": "The user wants a code review..."}
6
7event: tool_call
8data: {"toolName": "read_file", "args": {"path": "src/auth/jwt.service.ts"}, "status": "started"}
9
10event: file_change
11data: {"operation": "edited", "path": "src/auth/jwt.service.ts", "diff": "..."}
12
13event: todo_updated
14data: {"todos": [{"id": "1", "content": "Review JWT logic", "done": true}, ...]}
15
16event: question_asked
17data: {"questionId": "q_abc", "question": "Should I use RS256 or HS256?"}
18
19event: permission_asked
20data: {"permissionId": "p_abc", "action": "delete", "resource": "src/legacy/old-auth.ts"}
21
22event: done
23data: {"messageId": "msg_xyz", "totalTokens": 8500}
24
25event: error
26data: {"code": "TOOL_FAILED", "message": "Could not read file"}

1{
2  "data": [
3    {
4      "id": "msg_abc",
5      "sessionId": "cl123",
6      "threadId": "thr_main",
7      "role": "user",
8      "content": "Review the auth module",
9      "createdAt": "2026-04-27T10:30:00Z"
10    },
11    {
12      "id": "msg_def",
13      "sessionId": "cl123",
14      "threadId": "thr_main",
15      "role": "assistant",
16      "content": "I've reviewed the JWT authentication...",
17      "metadata": {
18        "tools": ["read_file", "list_directory"],
19        "inputTokens": 3200,
20        "outputTokens": 1800
21      },
22      "createdAt": "2026-04-27T10:30:45Z"
23    }
24  ],
25  "nextCursor": null
26}

1{
2  "data": [
3    {
4      "id": "evt_abc",
5      "sessionId": "cl123",
6      "threadId": "thr_main",
7      "seq": 1,
8      "type": "status_changed",
9      "payload": {"from": "creating", "to": "active"},
10      "createdAt": "2026-04-27T10:30:01Z"
11    },
12    {
13      "id": "evt_def",
14      "sessionId": "cl123",
15      "threadId": "thr_main",
16      "seq": 2,
17      "type": "file_created",
18      "payload": {"path": "src/auth/token-rotation.service.ts"},
19      "createdAt": "2026-04-27T10:31:00Z"
20    }
21  ]
22}

1{
2  "branch": "interactive/fix-auth-abc123",
3  "status": "clean",
4  "changes": [],
5  "commits": [
6    {"hash": "a1b2c3d", "message": "Add JWT token rotation", "author": "agent"}
7  ],
8  "pullRequest": {
9    "url": "https://github.com/org/repo/pull/42",
10    "number": 42,
11    "title": "Refactor JWT authentication"
12  }
13}

1{
2  "canMerge": true,
3  "conflicts": [],
4  "checks": [
5    {"name": "no-conflicts", "passed": true},
6    {"name": "up-to-date", "passed": true}
7  ]
8}

1// All tools from a provider
2{ "kind": "provider", "providerKind": "mcp_server", "resourceId": "<uuid>" }
3
4// A single tool from a provider
5{
6  "kind": "tool",
7  "providerKind": "org_database_explorer",
8  "resourceId": "<database-id>",
9  "toolName": "run-query"
10}

1{
2  "data": [
3    {
4      "id": "preview-123",
5      "kind": "next_dev",
6      "port": 3000,
7      "status": "running",
8      "url": "https://preview.xema.dev/s/abc123/3000",
9      "startedAt": "2026-04-27T10:35:00Z"
10    }
11  ]
12}