Send Session Input

POST/v1/agents/sessions/{session_id}/events

Send exactly one event per request: agent.session.input.message or agent.session.input.cancel. Returns 202 with no body; follow progress on the event stream. The SandBase extension form {"input": "…", "file_ids": [...]} sends text with up to 10 ready attachments and cannot be combined with events. A 409 session_input_pending means earlier input is still being delivered: wait, and do not resend with a new key.

Path parameters

stringsession_idrequired

Session ID (ses_ prefix).

Headers

Optional<string>Idempotency-Key

Optional but recommended. Reuse the same key when retrying the same input.

Request body

Either events or input/file_ids.

Optional<array>events

Exactly one event. input.message carries input as text or one user input_text message; input.cancel carries no input.

Optional<string>input

SandBase extension. Non-empty text up to 256 KiB.

Optional<array>file_ids

SandBase extension. Up to 10 distinct attachment IDs with status ready.

curl -X POST https://api.sandbase.ai/v1/agents/sessions/ses_5b0e7c3a-91d2-5f4e-8a6b-2c9d4e1f7a83/events \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Idempotency-Key: market-scan-input-1" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "agent.session.input.message",
        "input": [
          {
            "role": "user",
            "content": [
              {
                "type": "input_text",
                "text": "List three notable launches this week."
              }
            ]
          }
        ]
      }
    ]
  }'