Skip to main content

Send session events

Write user or system input events to a Forward Session.

Request Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key for requests with side effects.

Path Parameters

ParameterTypeRequiredDescription
session_idstringYesSession ID.

Request Body

FieldTypeRequiredDescription
eventsarrayYesArray of event objects
events[].typestringYesEvent type
events[].contentstring \arrayDepends on type
events[].content[].typestringYesContent block type, e.g. text
events[].content[].textstringYesText content
content supports two formats:
  • Shorthand: plain string "content": "text content"
  • Full: content block array "content": [{"type": "text", "text": "text content"}]
The shorthand is recommended for plain text messages; use the full format when sending multimedia content (such as images).

Supported Event Types

typeDescriptionRequired fields
user.messageUser sends a messagecontent
user.interruptUser interrupts Agent execution-
user.tool_confirmationAuthorize an Agent tool calltool_use_id, decision (approve or deny)
user.custom_tool_resultReturn the execution result of a custom tooltool_use_id, content
user.define_outcomeUser defines the expected outcomecontent

Example Request

curl -s -X POST 'https://api.qoder.com.cn/api/v1/forward/sessions/sess_xxx/events' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Continue the analysis."
        }
      ],
      "file_attachments": []
    }
  ]
}'

Example Response

HTTP 200 OK 
{
  "data": [
    {
      "id": "evt_xxx",
      "type": "user.message",
      "session_id": "sess_xxx",
      "content": [
        {
          "type": "text",
          "text": "Continue the analysis."
        }
      ],
      "processed_at": "2026-06-22T11:00:00Z"
    }
  ]
}

Response Fields

FieldTypeDescription
dataarrayArray of created Event objects, filtered by Forward rules.

Errors

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_eventEvent type or fields are invalid.
404not_found_errorsession_not_foundSession does not exist.
409conflict_errorsession_archivedSession is archived.
409conflict_errorturn_already_runningCurrent Turn state does not allow starting a new Turn.
404not_found_errorpending_action_not_foundTool confirmation or result has no matching Pending Action.
409conflict_errorpending_action_already_resolvedPending Action was already resolved.
401-TOKEN_INVALIDPAT invalid or expired, or Authorization header missing.

Notes