Skip to main content

​
Create Session

Create a new session to store context blocks.

​
Request Body

​
name
string
required
Session name
​
defaultAgent
string
Default agent for invocations in this session
​
tags
array
Tags for organization
​
fromSession
string
Fork from existing session ID
​
includeByTag
array
When forking, only include blocks with these tags
​
includePinned
boolean
default:"true"
When forking, include pinned blocks
curl -X POST https://api.runtools.ai/v1/aip/sessions \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auth Feature - Q1",
    "defaultAgent": "code-assistant",
    "tags": ["project-x", "auth"]
  }'

{
  "data": {
    "id": "sess_abc123",
    "name": "Auth Feature - Q1",
    "defaultAgent": "code-assistant",
    "tags": ["project-x", "auth"],
    "metrics": {
      "totalTokens": 0,
      "tokensRemainingPct": 100,
      "compactionCount": 0,
      "blockCount": 0
    },
    "createdAt": "2026-01-21T10:00:00Z"
  }
}

​
List Sessions

List all sessions.

​
Query Parameters

​
limit
number
default:"20"
Results per page
​
cursor
string
Pagination cursor
​
tag
string
Filter by tag
curl https://api.runtools.ai/v1/aip/sessions?tag=project-x \
  -H "X-API-Key: rt_live_xxx"

{
  "data": [
    {
      "id": "sess_abc123",
      "name": "Auth Feature - Q1",
      "metrics": { "totalTokens": 45000, "blockCount": 34 },
      "updatedAt": "2026-01-21T14:30:00Z"
    }
  ],
  "meta": {
    "hasMore": false
  }
}

​
Get Session

Get session details including metrics and block list.

​
Path Parameters

​
sessionId
string
required
Session ID
curl https://api.runtools.ai/v1/aip/sessions/sess_abc123 \
  -H "X-API-Key: rt_live_xxx"

{
  "data": {
    "id": "sess_abc123",
    "name": "Auth Feature - Q1",
    "defaultAgent": "code-assistant",
    "tags": ["project-x", "auth"],
    "metrics": {
      "totalTokens": 45000,
      "maxTokens": 200000,
      "tokensRemainingPct": 77.5,
      "compactionCount": 2,
      "blockCount": 34,
      "invocationCount": 89
    },
    "blocks": ["blk_001", "blk_002", "blk_003"],
    "pinnedBlocks": ["blk_001"],
    "createdAt": "2026-01-04T09:00:00Z",
    "updatedAt": "2026-01-21T14:30:00Z"
  }
}

​
Fork Session

Create a new session from an existing one with selected context.

​
Path Parameters

​
sessionId
string
required
Session ID to fork from

​
Request Body

​
name
string
required
Name for the new session
​
includeByTag
array
Only include blocks with these tags
​
excludeByTag
array
Exclude blocks with these tags
​
includePinned
boolean
default:"true"
Include pinned blocks regardless of tags
​
includeSummaries
boolean
default:"true"
Include summary blocks
curl -X POST https://api.runtools.ai/v1/aip/sessions/sess_abc123/fork \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auth Deep Dive",
    "includeByTag": ["authentication", "security"],
    "includePinned": true
  }'

{
  "data": {
    "id": "sess_def456",
    "name": "Auth Deep Dive",
    "forkedFrom": "sess_abc123",
    "metrics": {
      "totalTokens": 12000,
      "blockCount": 8
    },
    "createdAt": "2026-01-21T15:00:00Z"
  }
}

​
Delete Session

Delete a session and all its blocks.

​
Path Parameters

​
sessionId
string
required
Session ID
curl -X DELETE https://api.runtools.ai/v1/aip/sessions/sess_abc123 \
  -H "X-API-Key: rt_live_xxx"

{
  "data": {
    "deleted": true
  }
}

​
Compact Session

Trigger AI compaction to reduce token usage.

​
Request Body

​
targetTokens
number
Target token count after compaction
​
preservePinned
boolean
default:"true"
Don’t compact pinned blocks
​
preserveRecent
number
default:"5"
Number of recent blocks to preserve
curl -X POST https://api.runtools.ai/v1/aip/sessions/sess_abc123/compact \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "targetTokens": 50000,
    "preservePinned": true
  }'

{
  "data": {
    "previousTokens": 150000,
    "newTokens": 48000,
    "blocksCompacted": 25,
    "summariesCreated": 3
  }
}