Endpoints

Method	Path	Description
GET	/meta	Get available agents and their tools
GET	/sessions	List sessions
GET	/session/:id	Get a session by ID
PUT	/session	Create a new session
POST	/session/:id	Send a new turn to an existing session
DELETE	/session/:id	Delete a session

Authentication

All endpoints accept an API key via the Authorization header:

Authorization: Bearer <api-key>

Auth is optional on GET /meta — servers may choose to expose it publicly for capability discovery.

GET /meta

Returns the protocol version and the list of agents available on this server.

Response

{
  "version": 1,
  "agents": [
    {
      "name": "research-agent",
      "title": "Research Agent",
      "version": "1.2.0",
      "description": "A research agent that can search the web and summarize information.",
      "tools": [
        {
          "name": "web_search",
          "title": "Web Search",
          "description": "Search the web for information",
          "inputSchema": {
            "type": "object",
            "properties": {
              "query": { "type": "string", "description": "Search query" }
            },
            "required": ["query"]
          }
        }
      ],
      "options": [
        {
          "name": "model",
          "title": "Model",
          "description": "The LLM model to use for this agent.",
          "type": "select",
          "options": ["claude-sonnet-4-5", "claude-opus-4-5"],
          "default": "claude-sonnet-4-5"
        },
        {
          "name": "language",
          "title": "Response Language",
          "description": "The language the agent should respond in.",
          "type": "text",
          "default": "English"
        }
      ],
      "capabilities": {
        "history": {
          "compacted": {},
          "full": {}
        },
        "stream": {
          "delta": {},
          "message": {},
          "none": {}
        },
        "application": {
          "tools": {}
        }
      }
    }
  ]
}

Agent fields:

• name — unique identifier for the agent on this server.
• title — (optional) human-readable display name.
• version — semantic version of the agent.
• description — (optional) human-readable description of what the agent does.
• tools — server-side tools this agent can invoke. The client references them by name in requests. This list may be a subset of the agent's actual tools — agents may choose not to expose all tools.
• options — configurable options the client may set per request.
• capabilities — (optional) declares what the agent supports. Individual capability fields may be omitted; clients should treat missing fields as unsupported.
  • history — declares what history the agent can return in GET /session/:id:
    • history.compacted — if present, the server can return compacted history in GET /session/:id.
    • history.full — if present, the server can return full uncompacted history in GET /session/:id.
  • stream — declares which stream modes the agent supports. If omitted, clients should assume only "none" is supported.
    • stream.delta — if present, the agent supports "delta" streaming.
    • stream.message — if present, the agent supports "message" streaming.
    • stream.none — if present, the agent supports non-streaming ("none") responses.
  • application — declares what application-provided inputs the agent supports:
    • application.tools — if present, the agent accepts application-side tools in requests.

Option fields:

• name — identifier used as the key in the request options object.
• title — (optional) human-readable display name.
• description — (optional) explains what this option does.
• type — "text" for free-form string input, "select" for a fixed list of choices, "secret" for sensitive values (e.g. API keys) that should be masked in the UI.
• options — (required for select) list of allowed values.
• default — default value used if the client omits this option.

GET /sessions

Returns a paginated list of session IDs.

Query Parameters

• after — (optional) pagination cursor. Pass the nextCursor value from the previous response to get the next page.

Response

{
  "sessions": ["sess_abc123", "sess_def456"],
  "nextCursor": "sess_def456"
}

Fields:

• sessions — array of session IDs.
• nextCursor — (optional) opaque cursor string; pass as after to retrieve the next page. Absent when there are no more results.

GET /session/:id

Returns the full session object for the given session ID.

Response

{
  "sessionId": "sess_abc123",
  "agent": {
    "name": "research-agent",
    "tools": [
      { "name": "web_search", "trust": true }
    ],
    "options": {
      "model": "claude-opus-4-5",
      "language": "Japanese"
    }
  },
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    }
  ],
  "history": {
    "compacted": [...],
    "full": [...]
  }
}

Fields:

• sessionId — the session identifier.
• agent — the agent configuration for this session.
• tools — application-side tools declared for this session.
• history — (optional) conversation history. If the agent declared capabilities.history.compacted or capabilities.history.full in GET /meta, the server must return the corresponding field(s). Otherwise the server may omit them.
  • compacted — the server's compacted conversation history.
  • full — the full uncompacted conversation history.

PUT /session

Creates a new session. The server returns a sessionId the client uses for subsequent turns.

Request Body

{
  "agent": {
    "name": "research-agent",
    "tools": [{ "name": "web_search", "trust": true }],
    "options": {
      "model": "claude-opus-4-5",
      "language": "Japanese"
    }
  },
  "stream": "delta",
  "messages": [
    { "role": "user", "content": "What's the capital of France?" },
    { "role": "assistant", "content": "The capital of France is Paris." },
    { "role": "user", "content": "What's the weather in Tokyo?" }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    }
  ]
}

Fields:

• agent — (required) agent configuration.
  • agent.name — agent name to invoke.
  • agent.tools — (optional) server-side tools to enable.
  • agent.options — (optional) key-value pairs matching the agent's declared options.
• stream — (optional) response mode: "delta", "message", or "none" (default). See Response Modes.
• messages — (required) conversation history to seed the session with. The last message must be a user message, which becomes the first turn.
• tools — (optional) application-side tools with full schema.

agent.tools object fields:

• name — server tool name as declared in /meta.
• trust — if true, the server may invoke this tool without requesting client permission.

Response

Returns the sessionId followed by the agent's response stream (or JSON body).

For non-streaming mode:

{
  "sessionId": "sess_abc123",
  "stopReason": "end_turn",
  "messages": [
    {
      "role": "assistant",
      "content": "The weather in Tokyo is 18°C, partly cloudy."
    }
  ]
}

For SSE modes, sessionId is returned in the session_start event at the beginning of the stream. See SSE Events.

POST /session/:id

Send a new user turn or tool calling results to an existing session. The server appends the message to its history, runs the agent, and streams or returns the response.

Request Body

{
  "agent": {
    "tools": [{ "name": "web_search", "trust": true }],
    "options": {
      "language": "English"
    }
  },
  "stream": "delta",
  "messages": [{ "role": "user", "content": "What about Osaka?" }],
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      }
    }
  ]
}

Fields:

• agent — (optional) session-level agent overrides. The server must persist these for the lifetime of the session.
  • agent.tools — (optional) server-side tools. Overrides agent.tools declared at session creation.
  • agent.options — (optional) key-value option overrides. Overrides agent.options declared at session creation.
• stream — (optional) response mode. See Response Modes.
• messages — (required) the new turn(s) to append. Typically a single user message, but may also be tool results or tool permissions when re-submitting after a tool_use stop.
• tools — (optional) application-side tools. Overrides tools declared at session creation. The server must persist these for the lifetime of the session.

DELETE /session/:id

Deletes a session and its associated history.

Response

204 No Content