Topolo Docs Topolo Platform
Open workspace

Get thread

Reads the caller-owned thread in the bound organization and workspace, including its messages, visible context and attachment metadata. It does not send a message or run an agent.

Get thread

Outcome

Reads the caller-owned thread in the bound organization and workspace, including its messages, visible context and attachment metadata. It does not send a message or run an agent.

Before you start

  • Verify the intended environment, authenticated identity and organization before discovery.
  • Discover the published workspace:read application permission and inspect the credential-scoped action contract.
  • Discover and bind the granted canonical Agent workspace separately from the action input.
  • Fixture identifiers and simulated responses confer no live access. Replace identifiers through granted resource discovery.

Discover the target

  • topolo whoami --json
  • topolo workspaces list topolo-agent --json
  • topolo actions get app_topolo_agent.threads.get --detail --json
  • Read app_topolo_agent.threads.list in this same authorized context and select the returned identifier. Do not derive ids from display names.
  • Inspect app_topolo_agent.threads.attachments.list in the same credential and resource context before reading it.

Request

GET /api/threads/{id}

Input fields

FieldRequiredMeaning and constraints
idYesDiscovered resource identifier from app_topolo_agent.threads.list; retain the same organization and workspace context. Type: string. minLength: 1

Worked examples

Worked response 1 · HTTP 200

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "id": "thread_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.threads.get --data @payload.json --json
topolo actions plan app_topolo_agent.threads.get --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_agent.threads.get --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_read_action",
  "arguments": {
    "actionId": "app_topolo_agent.threads.get",
    "input": {
      "id": "thread_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 200:

{
  "success": true,
  "thread": {
    "id": "thread_docs_fixture",
    "title": "Fixture research thread",
    "threadKind": "workspace",
    "appSlug": null,
    "status": "active",
    "appScope": [
      "*"
    ],
    "preview": null,
    "created_at": 1,
    "updated_at": 1,
    "last_message_at": 1,
    "orgSlug": "org_docs_fixture",
    "orgLabel": "org_docs_fixture",
    "composerPlaceholder": "Ask the agent to work inside all Topolo apps.",
    "messages": [],
    "suggestedReplies": [
      {
        "id": "scope-summary",
        "label": "Summarize org",
        "message": "Summarize what you know about this organization."
      },
      {
        "id": "scope-next",
        "label": "Next action",
        "message": "What is the next best action in all Topolo apps?"
      },
      {
        "id": "scope-output",
        "label": "Latest outputs",
        "message": "Show me the latest outputs in this scope."
      },
      {
        "id": "scope-apps",
        "label": "Thread scope",
        "message": "What apps are included in this thread?"
      }
    ],
    "suggestedReplyConfig": {
      "mode": "single"
    },
    "liveBrief": null,
    "websiteImport": null,
    "appOnboarding": null,
    "globalKnowledge": [],
    "attachments": [
      {
        "id": "attachment_docs_fixture",
        "filename": "brief.txt",
        "contentType": "text/plain",
        "sizeBytes": 13,
        "visibilityScope": "thread",
        "status": "ready",
        "created_at": 1,
        "downloadUrl": "/api/threads/thread_docs_fixture/attachments/attachment_docs_fixture/download"
      },
      {
        "id": "attachment_binary_fixture",
        "filename": "evidence.bin",
        "contentType": "application/octet-stream",
        "sizeBytes": 4,
        "visibilityScope": "thread",
        "status": "ready",
        "created_at": 1,
        "downloadUrl": "/api/threads/thread_docs_fixture/attachments/attachment_binary_fixture/download"
      },
      {
        "id": "attachment_json_fixture",
        "filename": "context.json",
        "contentType": "application/json",
        "sizeBytes": 16,
        "visibilityScope": "thread",
        "status": "ready",
        "created_at": 1,
        "downloadUrl": "/api/threads/thread_docs_fixture/attachments/attachment_json_fixture/download"
      }
    ],
    "contextItems": [
      {
        "id": "attachment_attachment_docs_fixture",
        "kind": "attachment",
        "title": "brief.txt",
        "summary": "Uploaded thread context document (1 KB).",
        "sourceLabel": "Thread attachment",
        "created_at": 1,
        "url": "/api/threads/thread_docs_fixture/attachments/attachment_docs_fixture/download"
      },
      {
        "id": "attachment_attachment_binary_fixture",
        "kind": "attachment",
        "title": "evidence.bin",
        "summary": "Uploaded thread context document (1 KB).",
        "sourceLabel": "Thread attachment",
        "created_at": 1,
        "url": "/api/threads/thread_docs_fixture/attachments/attachment_binary_fixture/download"
      },
      {
        "id": "attachment_attachment_json_fixture",
        "kind": "attachment",
        "title": "context.json",
        "summary": "Uploaded thread context document (1 KB).",
        "sourceLabel": "Thread attachment",
        "created_at": 1,
        "url": "/api/threads/thread_docs_fixture/attachments/attachment_json_fixture/download"
      }
    ]
  }
}

successful: HTTP 200; seeded local fixture identifiers confer no live access.

Worked response 2 · HTTP 401

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "id": "thread_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.threads.get --data @payload.json --json
topolo actions plan app_topolo_agent.threads.get --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_agent.threads.get",
    "input": {
      "id": "thread_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 401:

{
  "success": false,
  "error": "Organization context required"
}

organization context missing: HTTP 401; SDK code auth_error; seeded local fixture identifiers confer no live access.

Worked response 3 · HTTP 404

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.

Input · payload.json:

{
  "id": "thread_docs_fixture"
}

CLI:

topolo actions validate app_topolo_agent.threads.get --data @payload.json --json
topolo actions plan app_topolo_agent.threads.get --resource-type workspace --resource-id "$AGENT_WORKSPACE_ID" --data @payload.json --json

MCP tool and arguments:

{
  "tool": "topolo_prepare_action",
  "arguments": {
    "actionId": "app_topolo_agent.threads.get",
    "input": {
      "id": "thread_docs_fixture"
    },
    "resourceType": "workspace",
    "resourceId": "<identifier returned by granted resource discovery>"
  }
}

Captured local response · HTTP 404:

{
  "success": false,
  "error": "Thread not found"
}

outside workspace: HTTP 404; SDK code http_error; seeded local fixture identifiers confer no live access.

Verify the result

  • Confirm thread.id and orgSlug, then inspect appScope, messages, attachments and contextItems. Suggested replies are available prompts, not executed work.

Errors and recovery

  • auth_error (HTTP 401): For an unstructured HTTP 401 response, authenticate and verify the intended organization and workspace before retrying.
  • permission_denied (HTTP 403): For an unstructured HTTP 403 response, use the published application permission and required resource-level access. Do not retry with broader context.
  • http_error (HTTP 404): For an unstructured HTTP 404 response, refresh the corresponding resource listing in the same context. Private resources can be deliberately hidden from this caller.

Authentication, input validation or resource middleware can refuse a request before these handlers. Preserve the actual refusal and request id.

Recovery boundary

This read does not change service state. Re-discover the target in the same authorized organization and workspace after a missing or hidden-resource refusal; do not guess identifiers or widen context.

  • List thread attachments: List the files attached to one thread, with their names and types but not their contents.

Evidence

Actual exported read handlers and replayed SQLite migrations. Auth directory, service-token, R2 object storage and Durable Object storage boundaries are simulated; session response serialization executes the actual AgentSession.onRequest method. Egress is sealed. No deployed/provider outcome or live access is demonstrated.