Sessions API

Overview

Sessions store conversation history between the user and the agent. Each session has a unique key and includes all messages, timestamps, and metadata. The Sessions API provides CRUD operations for managing these sessions.

GET /api/v1/sessions

List all session keys with metadata.

Request

curl -X GET http://127.0.0.1:8080/api/v1/sessions \
  -H "Authorization: Bearer YOUR_TOKEN"

No parameters required.

Response

sessions

array

Array of session key strings.

count

integer

Total number of sessions.

Example Response

{
  "sessions": [
    "api:a3f9c2e8b1d4",
    "user:alice:project-planning",
    "telegram:123456789",
    "cli:default"
  ],
  "count": 4
}

Python Example

import httpx

url = "http://127.0.0.1:8080/api/v1/sessions"
headers = {"Authorization": f"Bearer {token}"}

response = httpx.get(url, headers=headers)
data = response.json()

print(f"Found {data['count']} sessions:")
for session_key in data['sessions']:
    print(f"  - {session_key}")

GET /api/v1/sessions/

Get detailed information about a specific session.

Request

curl -X GET http://127.0.0.1:8080/api/v1/sessions/user:alice:project-planning \
  -H "Authorization: Bearer YOUR_TOKEN"

key

string

required

The session key (URL path parameter). Can contain slashes, colons, and special characters.

Session keys can contain special characters like colons and slashes. URL-encode keys if they contain spaces or other reserved characters.

Response

key

string

The session key.

message_count

integer

Total number of messages (user + assistant) in the session.

created_at

number

Unix timestamp (seconds since epoch) when the session was created.

updated_at

number

Unix timestamp when the session was last updated.

age_seconds

number

Time in seconds since the session was created (rounded to 1 decimal place).

Example Response

{
  "key": "user:alice:project-planning",
  "message_count": 18,
  "created_at": 1709125200.5,
  "updated_at": 1709128800.3,
  "age_seconds": 3599.5
}

Python Example

import httpx
from datetime import datetime

url = "http://127.0.0.1:8080/api/v1/sessions/user:alice:project-planning"
headers = {"Authorization": f"Bearer {token}"}

response = httpx.get(url, headers=headers)
data = response.json()

print(f"Session: {data['key']}")
print(f"Messages: {data['message_count']}")
print(f"Created: {datetime.fromtimestamp(data['created_at'])}")
print(f"Age: {data['age_seconds'] / 3600:.1f} hours")

Error Responses

404 Not Found - Session does not exist:

{
  "detail": "Session not found"
}

DELETE /api/v1/sessions/

Delete a session by key. This permanently removes the session file and all conversation history.

Request

curl -X DELETE http://127.0.0.1:8080/api/v1/sessions/api:a3f9c2e8b1d4 \
  -H "Authorization: Bearer YOUR_TOKEN"

key

string

required

The session key to delete (URL path parameter).

Deletion is permanent and cannot be undone. The session file is removed from disk immediately.

Response

deleted

boolean

Always true on successful deletion.

key

string

The session key that was deleted.

Example Response

{
  "deleted": true,
  "key": "api:a3f9c2e8b1d4"
}

Python Example

import httpx

url = "http://127.0.0.1:8080/api/v1/sessions/api:a3f9c2e8b1d4"
headers = {"Authorization": f"Bearer {token}"}

response = httpx.delete(url, headers=headers)
data = response.json()

if data['deleted']:
    print(f"Successfully deleted session: {data['key']}")

Error Responses

404 Not Found - Session does not exist:

{
  "detail": "Session not found"
}

Session File Structure

Sessions are stored as JSON files in <workspace>/sessions/:

~/.grip/workspace/sessions/
  ├── api:a3f9c2e8b1d4.json
  ├── user:alice:project-planning.json
  └── cli:default.json

Each session file contains:

{
  "key": "user:alice:project-planning",
  "messages": [
    {
      "role": "user",
      "content": "Create a new feature branch",
      "timestamp": 1709125200.5
    },
    {
      "role": "assistant",
      "content": "I'll create a new feature branch...",
      "timestamp": 1709125202.1
    }
  ],
  "created_at": 1709125200.5,
  "updated_at": 1709128800.3
}

Session Key Formats

Session keys follow different patterns depending on the source:

Source	Format	Example
API (auto)	`api:<12-hex>`	`api:a3f9c2e8b1d4`
API (custom)	User-defined	`user:alice:project-planning`
CLI	`cli:default`	`cli:default`
Telegram	`telegram:<user-id>`	`telegram:123456789`
Discord	`discord:<user-id>`	`discord:987654321`
Slack	`slack:<user-id>`	`slack:U01234ABCDE`

Custom keys must match regex ^[\w:.@-]+$ (max 128 characters).

Bulk Operations

Delete Multiple Sessions

No bulk delete endpoint exists. To delete multiple sessions, iterate:

import httpx

base_url = "http://127.0.0.1:8080"
headers = {"Authorization": f"Bearer {token}"}

# Get all sessions
response = httpx.get(f"{base_url}/api/v1/sessions", headers=headers)
sessions = response.json()["sessions"]

# Delete sessions starting with "api:"
for key in sessions:
    if key.startswith("api:"):
        httpx.delete(f"{base_url}/api/v1/sessions/{key}", headers=headers)
        print(f"Deleted {key}")

Export Session Data

To export conversation history, read the session files directly:

import json
from pathlib import Path

workspace = Path.home() / ".grip" / "workspace"
sessions_dir = workspace / "sessions"

for session_file in sessions_dir.glob("*.json"):
    data = json.loads(session_file.read_text())
    print(f"\n=== {data['key']} ===")
    print(f"Messages: {len(data['messages'])}")
    for msg in data['messages']:
        print(f"  {msg['role']}: {msg['content'][:50]}...")

Rate Limiting

All session endpoints are subject to standard rate limits:

Per-IP: 60 requests/min
Per-token: 60 requests/min

See Overview - Rate Limits.

Best Practices

Use descriptive session keys

Custom keys like user:alice:project-planning are easier to manage than auto-generated keys like api:a3f9c2e8b1d4.

Clean up old sessions periodically

List sessions, filter by age or prefix, and delete unused ones to save disk space.

Back up important sessions

Copy session JSON files before deletion or server migration. They’re stored in <workspace>/sessions/.

Monitor session count

Use the list endpoint to track total sessions. Set up alerts if the count grows unexpectedly.

REST API

CLI Commands

Built-in Tools

Overview

GET /api/v1/sessions

Request

Response

Example Response

Python Example

GET /api/v1/sessions/

Request

Response

Example Response

Python Example

Error Responses

DELETE /api/v1/sessions/

Request

Response

Example Response

Python Example

Error Responses

Session File Structure

Session Key Formats

Bulk Operations

Delete Multiple Sessions

Export Session Data

Rate Limiting

Best Practices

Next Steps

Chat API

Management API

Build docs developers (and LLMs) love

REST API

CLI Commands

Built-in Tools

​Overview

​GET /api/v1/sessions

​Request

​Response

​Example Response

​Python Example

​GET /api/v1/sessions/

​Request

​Response

​Example Response

​Python Example

​Error Responses

​DELETE /api/v1/sessions/

​Request

​Response

​Example Response

​Python Example

​Error Responses

​Session File Structure

​Session Key Formats

​Bulk Operations

​Delete Multiple Sessions

​Export Session Data

​Rate Limiting

​Best Practices

​Next Steps

Chat API

Management API

Build docs developers (and LLMs) love

Overview

GET /api/v1/sessions

Request

Response

Example Response

Python Example

GET /api/v1/sessions/

Request

Response

Example Response

Python Example

Error Responses

DELETE /api/v1/sessions/

Request

Response

Example Response

Python Example

Error Responses

Session File Structure

Session Key Formats

Bulk Operations

Delete Multiple Sessions

Export Session Data

Rate Limiting

Best Practices

Next Steps