Skip to main content
POST
/
v1
/
instances
/
{instance_id}
/
session
/
{session_id}
/
responses
curl -X POST https://api.chowder.dev/v1/instances/f47ac10b-58cc-4372-a567-0e02b2c3d479/session/user-42/responses \
  -H "Authorization: Bearer chd_org_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "input": "Summarize the README for me."
  }'

{
  "id": "resp_a1b2c3d4e5f6",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The README describes a Node.js project that..."
        }
      ]
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "usage": {
    "input_tokens": 35,
    "output_tokens": 52,
    "total_tokens": 87
  }
}
Same as Send Message, but routes the request to a specific named session on the OpenClaw instance. Sessions let you run multiple independent conversations on the same instance without them sharing context. The session_id is a string you choose — if the session doesn’t exist yet, it’s created automatically. Use the same session_id across requests to maintain continuity within that session.
Accepts an organization key (chd_org_*) or a scoped key (chd_sk_*) with interact permission on this instance.

​
Path Parameters

​
instance_id
string
required
The ID of the instance to send a message to.
​
session_id
string
required
A session identifier you choose. Can be any string — e.g. a user ID, a ticket number, or a UUID. Sessions are created on first use.

​
Request Body

Identical to Send Message. At minimum, provide model and input.
​
model
string
required
The model to use (e.g. "claude-sonnet-4-20250514", "gpt-4o").
​
input
string
required
The user message to send.
Any additional OpenResponses API fields (e.g. instructions, tools, previous_response_id) are passed through as-is.

​
Response

Returns 200 OK with the same OpenResponses API response format as Send Message. 
curl -X POST https://api.chowder.dev/v1/instances/f47ac10b-58cc-4372-a567-0e02b2c3d479/session/user-42/responses \
  -H "Authorization: Bearer chd_org_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "input": "Summarize the README for me."
  }'

{
  "id": "resp_a1b2c3d4e5f6",
  "object": "response",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The README describes a Node.js project that..."
        }
      ]
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "usage": {
    "input_tokens": 35,
    "output_tokens": 52,
    "total_tokens": 87
  }
}

​
When to Use Sessions

Sessions are useful when your instance serves multiple users or conversations:
  • Per-user isolation: Use the user’s ID as the session_id so each user gets their own conversation history.
  • Per-ticket support: Use a ticket or thread ID so the agent maintains context for each support case.
  • A/B testing: Run different prompts against the same instance in separate sessions.
Without sessions, all messages to an instance share the same default conversation context.