Skip to main content

​
Create Block

Create a new context block in a session.

​
Request Body

​
sessionId
string
required
Session to add block to
​
type
string
required
Block type: conversation, file, diff, event, note, summary, tool_result
​
content
object
required
Block content (structure depends on type)
​
tags
array
Tags for organization and filtering
​
pinned
boolean
default:"false"
Pinned blocks won’t be compacted
​
importance
number
Importance score (0-1). Auto-calculated if not provided.
curl -X POST https://api.runtools.ai/v1/aip/blocks \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "sess_abc123",
    "type": "note",
    "content": "User prefers TypeScript with functional style",
    "tags": ["preferences", "coding-style"],
    "pinned": true
  }'

{
  "data": {
    "id": "blk_xyz789",
    "sessionId": "sess_abc123",
    "type": "note",
    "content": "User prefers TypeScript with functional style",
    "metadata": {
      "tokenCount": 12,
      "tags": ["preferences", "coding-style"],
      "pinned": true,
      "importance": 0.9,
      "compactionLevel": 0
    },
    "createdAt": "2026-01-21T10:00:00Z"
  }
}

​
Block Content by Type

{
  "type": "conversation",
  "content": [
    { "role": "user", "content": "How should we handle auth?" },
    { "role": "assistant", "content": "I recommend JWT with refresh tokens..." }
  ]
}

{
  "type": "file",
  "content": {
    "path": "/src/auth.ts",
    "content": "export function authenticate() { ... }",
    "language": "typescript"
  }
}

{
  "type": "diff",
  "content": {
    "path": "/src/auth.ts",
    "diff": "@@ -1,3 +1,5 @@\n+import { jwt } from 'jsonwebtoken';\n..."
  }
}

{
  "type": "note",
  "content": "Decision: Use PostgreSQL for the main database"
}

{
  "type": "tool_result",
  "content": {
    "tool": "bash",
    "input": { "command": "npm test" },
    "output": "All 42 tests passed"
  }
}

​
List Blocks

List blocks in a session.

​
Query Parameters

​
type
string
Filter by block type
​
tag
string
Filter by tag
​
pinned
boolean
Filter pinned blocks only
​
limit
number
default:"50"
Results per page
curl "https://api.runtools.ai/v1/aip/sessions/sess_abc123/blocks?tag=authentication" \
  -H "X-API-Key: rt_live_xxx"

{
  "data": [
    {
      "id": "blk_001",
      "type": "conversation",
      "metadata": {
        "tokenCount": 1200,
        "tags": ["authentication", "jwt"],
        "importance": 0.85
      },
      "createdAt": "2026-01-20T10:00:00Z"
    },
    {
      "id": "blk_002",
      "type": "file",
      "metadata": {
        "tokenCount": 450,
        "tags": ["authentication"],
        "path": "/src/auth.ts"
      },
      "createdAt": "2026-01-20T11:00:00Z"
    }
  ]
}

​
Get Block

Get full block content.

​
Path Parameters

​
blockId
string
required
Block ID
curl https://api.runtools.ai/v1/aip/blocks/blk_xyz789 \
  -H "X-API-Key: rt_live_xxx"

{
  "data": {
    "id": "blk_xyz789",
    "sessionId": "sess_abc123",
    "type": "conversation",
    "content": [
      { "role": "user", "content": "How should we handle JWT expiration?" },
      { "role": "assistant", "content": "I recommend 15-minute access tokens with 7-day refresh tokens..." }
    ],
    "metadata": {
      "tokenCount": 850,
      "tags": ["authentication", "jwt", "architecture-decision"],
      "importance": 0.92,
      "pinned": false,
      "compactionLevel": 0
    },
    "createdAt": "2026-01-20T10:00:00Z"
  }
}

​
Update Block Tags

Add or remove tags from a block.

​
Request Body

​
add
array
Tags to add
​
remove
array
Tags to remove
curl -X PATCH https://api.runtools.ai/v1/aip/blocks/blk_xyz789/tags \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "add": ["reviewed", "approved"],
    "remove": ["draft"]
  }'

{
  "data": {
    "id": "blk_xyz789",
    "tags": ["authentication", "jwt", "reviewed", "approved"]
  }
}

​
Pin/Unpin Block

Pin or unpin a block. Pinned blocks are preserved during compaction.

​
Request Body

​
pinned
boolean
required
Whether to pin the block
curl -X PATCH https://api.runtools.ai/v1/aip/blocks/blk_xyz789/pin \
  -H "X-API-Key: rt_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "pinned": true }'

​
Delete Block

Soft-delete a block (retained for audit). 
curl -X DELETE https://api.runtools.ai/v1/aip/blocks/blk_xyz789 \
  -H "X-API-Key: rt_live_xxx"

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