Send Message (Session)

POST

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

string

required

The ID of the instance to send a message to.

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.

string

required

The model to use (e.g. "claude-sonnet-4-20250514", "gpt-4o").

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.

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
  }
}

Overview

Organization

Instances

Channels

Skills

Files

API Keys

Subscription

Send Message (Session)

Path Parameters

Request Body

Response

When to Use Sessions

​Path Parameters

​Request Body

​Response

​When to Use Sessions

Path Parameters

Request Body

Response

When to Use Sessions