List Sessions

List your conversations with agents, most recent activity first.

GET /api/v1/sessions

cURL

curl "https://api.wordsmith.ai/api/v1/sessions?agent_id=3135e518-9205-4887-9ab1-1d56dd38eafb&limit=2" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "items": [
    {
      "id": "6d02931b-eaa1-4c77-b711-66038eb1bb2b",
      "agent_id": "3135e518-9205-4887-9ab1-1d56dd38eafb",
      "title": "Liability cap in the supply agreement",
      "url": "https://app.wordsmith.ai/chat/6d02931b-eaa1-4c77-b711-66038eb1bb2b",
      "created_at": "2026-10-13T14:02:11Z",
      "updated_at": "2026-10-13T14:09:47Z"
    },
    {
      "id": "c5d9f8e2-bc41-4b62-8d82-60dcf103e485",
      "agent_id": "3135e518-9205-4887-9ab1-1d56dd38eafb",
      "title": "Notice periods under the lease",
      "url": "https://app.wordsmith.ai/chat/c5d9f8e2-bc41-4b62-8d82-60dcf103e485",
      "created_at": "2026-10-13T09:30:05Z",
      "updated_at": "2026-10-13T09:31:12Z"
    }
  ],
  "cursor": "eyJvZmZzZXQiOjJ9"
}

Preview. This endpoint is available to organisations in the Wordsmith MCP pilot. Other organisations receive 403 mcp_not_enabled. See the preview overview.

Returns a page of your sessions, most recent activity first. Activity is compared to the second: sessions active within the same second come newest-created first, also compared to the second, and then in a fixed order by session id. So their updated_at values, which keep milliseconds, may not be in strict order, but every page continues the same order without repeating or skipping a session. A session is one conversation with an agent. The list holds the sessions you started, in the Wordsmith app or through the API, as the app’s own session list does. To read a session someone shared with you, use Get Session with its id.

Read a session’s messages with List Messages. These endpoints are read-only. To ask a question, in a new session or an existing one, use Create Question.

List items leave out message_count. Get Session returns it.

Authentication

Requires an API key, or an OAuth token with sessions:read.

Query parameters

agent_id · string

Only sessions with this agent. Find agent ids with List Agents.

query · string

Search session titles and message text, up to 200 characters, as the app’s session search does. Results come best match first instead of most recent first.

cursor · string

The cursor from the previous page. Omit it for the first page.

limit · integer · default: "50"

Sessions per page, from 1 to 200.

Response

Returns 200 with {"items": [...], "cursor": "..."}. Each item is a session. cursor is null on the last page.

id · string

The session id.

agent_id · string | null

The agent the session is with, as List Agents names it: default for the default agent.

title · string | null

The session’s title.

url · string

Opens the session in Wordsmith.

created_at · string

ISO 8601 UTC.

updated_at · string

When the last message was added. ISO 8601 UTC.

cURL

curl "https://api.wordsmith.ai/api/v1/sessions?agent_id=3135e518-9205-4887-9ab1-1d56dd38eafb&limit=2" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here"

Response

{
  "items": [
    {
      "id": "6d02931b-eaa1-4c77-b711-66038eb1bb2b",
      "agent_id": "3135e518-9205-4887-9ab1-1d56dd38eafb",
      "title": "Liability cap in the supply agreement",
      "url": "https://app.wordsmith.ai/chat/6d02931b-eaa1-4c77-b711-66038eb1bb2b",
      "created_at": "2026-10-13T14:02:11Z",
      "updated_at": "2026-10-13T14:09:47Z"
    },
    {
      "id": "c5d9f8e2-bc41-4b62-8d82-60dcf103e485",
      "agent_id": "3135e518-9205-4887-9ab1-1d56dd38eafb",
      "title": "Notice periods under the lease",
      "url": "https://app.wordsmith.ai/chat/c5d9f8e2-bc41-4b62-8d82-60dcf103e485",
      "created_at": "2026-10-13T09:30:05Z",
      "updated_at": "2026-10-13T09:31:12Z"
    }
  ],
  "cursor": "eyJvZmZzZXQiOjJ9"
}

Errors

Status	error_code	When
400	bad_request	limit is outside 1–200, cursor is not one this endpoint returned, or agent_id is not an agent id.
404	resource_not_found	No agent with this agent_id, or the caller cannot use it.
503	temporarily_unavailable	The session list could not be read just now. It is not empty: retry after a short wait.