Overview
Threads represent conversation sessions between users and the Loom AI agent. Each thread contains a sequence of messages, tool calls, and execution state.
Ownership: Users can only access threads they own. System administrators can access all threads.
Create or Update Thread
Creates a new thread or updates an existing one. Supports optimistic concurrency control via the If-Match header.
Path Parameters
Thread ID (must match ID in request body)
Expected thread version for optimistic locking
Request Body
Send the full Thread object (see loom-common-thread schema):
Thread ID (must match path parameter)
Visibility level: "private", "shared", or "public"
Thread version (increment on each update)
ISO 8601 timestamp (server will overwrite)
Response
New version number after upsert
ISO 8601 timestamp of last update
Example
curl -X PUT https://loom.ghuntley.com/api/threads/thread_abc123 \
-H "Authorization: Bearer loom_sk_..." \
-H "Content-Type: application/json" \
-H "If-Match: 5" \
-d '{
"id": "thread_abc123",
"title": "Fix login bug",
"workspace": "/home/user/project",
"visibility": "private",
"messages": [...],
"version": 5,
"updated_at": "2026-03-03T12:00:00Z"
}'
{
"id": "thread_abc123",
"title": "Fix login bug",
"workspace": "/home/user/project",
"visibility": "private",
"messages": [...],
"version": 6,
"updated_at": "2026-03-03T12:05:30Z"
}
{
"error": "version_conflict",
"message": "Expected version 5, but current version is 7"
}
Get Thread
Retrieves a single thread by ID. Only the thread owner (or system admin) can access.
Path Parameters
Response
Returns the full Thread object.
Example
curl -H "Authorization: Bearer loom_sk_..." \
https://loom.ghuntley.com/api/threads/thread_abc123
{
"id": "thread_abc123",
"title": "Fix login bug",
"workspace": "/home/user/project",
"visibility": "private",
"messages": [
{
"role": "user",
"content": "Help me fix the login bug",
"timestamp": "2026-03-03T12:00:00Z"
},
{
"role": "assistant",
"content": "I'll help you investigate the login bug.",
"timestamp": "2026-03-03T12:00:15Z"
}
],
"version": 6,
"updated_at": "2026-03-03T12:05:30Z",
"created_at": "2026-03-01T10:00:00Z"
}
{
"error": "not_found",
"message": "Thread not found"
}
List Threads
Lists threads owned by the authenticated user. Supports filtering by workspace and pagination.
Query Parameters
Filter by workspace root path
Maximum number of results (1-100)
Number of results to skip for pagination
Response
Array of ThreadSummary objects (lightweight version without full message history)
Total number of threads matching the filter
Example
curl "https://loom.ghuntley.com/api/threads?workspace=/home/user/project&limit=20&offset=0" \
-H "Authorization: Bearer loom_sk_..."
{
"threads": [
{
"id": "thread_abc123",
"title": "Fix login bug",
"workspace": "/home/user/project",
"visibility": "private",
"message_count": 12,
"updated_at": "2026-03-03T12:05:30Z",
"created_at": "2026-03-01T10:00:00Z"
},
{
"id": "thread_def456",
"title": "Add user settings page",
"workspace": "/home/user/project",
"visibility": "private",
"message_count": 8,
"updated_at": "2026-03-02T15:30:00Z",
"created_at": "2026-03-02T14:00:00Z"
}
],
"total": 47,
"limit": 20,
"offset": 0
}
Delete Thread
Soft-deletes a thread. Only the thread owner (or system admin) can delete.
Path Parameters
Response
Returns 204 No Content on success.
Example
curl -X DELETE https://loom.ghuntley.com/api/threads/thread_abc123 \
-H "Authorization: Bearer loom_sk_..."
204 No Content
Error (404 Not Found) if thread doesn’t exist or user doesn’t own it.
Update Thread Visibility
POST /api/threads/{id}/visibility
Path Parameters
Request Body
New visibility: "private", "shared", or "public"
Response
Returns the updated Thread object with incremented version.
Example
curl -X POST https://loom.ghuntley.com/api/threads/thread_abc123/visibility \
-H "Authorization: Bearer loom_sk_..." \
-H "If-Match: 6" \
-H "Content-Type: application/json" \
-d '{"visibility": "shared"}'
{
"id": "thread_abc123",
"title": "Fix login bug",
"visibility": "shared",
"version": 7,
"updated_at": "2026-03-03T13:00:00Z",
...
}
Search Threads
Full-text search across thread titles and messages. Searches only threads owned by the authenticated user.
Query Parameters
Maximum number of results
Response
Array of search results with relevance scores
Relevance score (higher = more relevant)
Example
curl "https://loom.ghuntley.com/api/threads/search?q=login+bug&limit=10" \
-H "Authorization: Bearer loom_sk_..."
{
"hits": [
{
"summary": {
"id": "thread_abc123",
"title": "Fix login bug",
"workspace": "/home/user/project",
"message_count": 12,
"updated_at": "2026-03-03T12:05:30Z"
},
"score": 0.92
},
{
"summary": {
"id": "thread_ghi789",
"title": "Login form validation",
"workspace": "/home/user/project",
"message_count": 5,
"updated_at": "2026-02-28T09:00:00Z"
},
"score": 0.67
}
],
"limit": 10,
"offset": 0
}
{
"error": "bad_request",
"message": "Empty search query"
}