Catalog

Search or list unified sessions

Changed on

The unified, cross-surface sessions feed for one project: Playground, user-testing, eval, and swarm transcripts in one list, newest first. Project-NESTED (unlike /chat-sessions) because projectId owns the scope here rather than filtering it.

Under x-mcpjam-api-vocabulary: 2 each item’s sourceType reads study where it reads scenario today, and parentRef reads kind: "study" / kind: "goalRun" with its id fields re-keyed to studyId / goalRunId / goalRefId. The sourceType filter accepts either spelling under that header.

Supplying q at all switches to relevance-ordered search; scope then chooses what is searched. Row-level visibility applies in every mode: a caller never receives another member's private Playground session.

The response echoes the honored scope. A deployment predating that parameter omits the echo — clients requesting a non-default scope MUST treat its absence as "unsupported" rather than accepting the results.

get/projects/{projectId}/sessions

Request

  • Base URL
    https://app.mcpjam.com/api/v1
  • URL
    https://app.mcpjam.com/api/v1/projects/{projectId}/sessions
  • Auth
    HTTP bearer

Path parameters

projectIdstring required

ID of the hosted project that contains the server.

Query parameters

qstring

Search terms. Supplying this at all switches from the recency feed to relevance-ordered search; q= (blank) is an empty search, not "no filter".

scope'titles' | 'transcripts'

What to search. titles (default) matches titles and opening messages; transcripts matches conversation content. Requires q; an unknown value is a 400.

sourceTypestring

Comma-separated surfaces to include: direct, scenario, eval, swarm. Omit for all. An unknown value is a 400 rather than a silent widening.

status'active' | 'archived'

active (default) or archived.

limitinteger

Page size, 1–200. Defaults to 50.

cursorstring

Opaque cursor: echo back the previous page's nextCursor. Never construct one, and never assume it encodes a timestamp. Cursors do not cross scopes — page with the parameters you opened with.

Headers

x-mcpjam-api-vocabulary'1' | '2'

Which spelling of the API's resource-noun VALUES this request and its response speak. Absent means 1, byte-for-byte today's contract. 2 is the canonical vocabulary. Any other value is a 400 with code: "VALIDATION_ERROR".

Three nouns were renamed at this boundary — scenario → study, journey → goal, wave → swarm run. Operation names, routes, type names and field names each moved behind a deprecated alias, because a caller reaches them by a name it chose. A VALUE cannot: sourceType is one field with one string in it, and a client switching on "scenario" has no second name to fall back to. Under vocabulary 2 a session’s sourceType reads study, a share’s resourceType reads study, and a session’s parentRef.kind reads study or goalRun with its id fields re-keyed to match.

On the way IN, a vocabulary-2 request may name a filter or a path segment by EITHER spelling; a vocabulary-1 request may use only the legacy one, because a boundary that accepts a spelling it does not announce is one two implementations can disagree about.

A response that varies by vocabulary sends Vary: x-mcpjam-api-vocabulary. A SEPARATE header from x-mcpjam-eval-vocabulary, which is eval-scoped by name and moves on its own schedule.

Response

One page of sessions — newest first when listing, most relevant first when searching.

nextCursorstring

Pass as cursor to fetch the next page. Omitted on the last page.

scope'titles' | 'transcripts'

The scope the server actually honored. ABSENT from deployments predating the parameter — treat its absence as "transcript search unsupported".

Changes

  • 561e4fd0dfa2Revision changes
    • warning

      added the new goalRun enum value to the /////// response property for the response status

    • warning

      added the new study enum value to the /////// response property for the response status

    • warning

      added the new study enum value to the // response property for the response status

    • info

      added the new optional header request parameter x-mcpjam-api-vocabulary

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

  • f338eb09898fRevision changes
    • warning

      removed the optional property /////// from the response with the status

    • warning

      added the new scenario enum value to the /////// response property for the response status

    • warning

      added the new scenario enum value to the // response property for the response status

    • info

      added the optional property /////// to the response with the status

    • info

      removed the chatbox enum value from the /////// response property for the response status

    • info

      removed the chatbox enum value from the // response property for the response status