Skip to main content
Events

Send session events

Send supported user input events to a Forward session.

POST /api/v1/forward/sessions/{session_id}/events Adds supported user input events to a session. Callers cannot forge agent or session status events.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoOptional idempotency key for unsafe requests.

Path parameters

ParameterTypeRequiredDescription
session_idstringYesSession ID.

Body parameters

ParameterTypeRequiredDescription
eventsarrayYesEvent objects to append.
events[].typestringYesInput Event type.
events[].contentarrayConditionalRequired for user.message; must be a non-empty content block array. Only text and image types are supported.
events[].tool_use_idstringConditionalRequired for user.tool_confirmation and user.tool_result.
events[].custom_tool_use_idstringConditionalRequired for user.custom_tool_result.
events[].resultstringConditionalRequired for user.tool_confirmation: allow or deny.
events[].deny_messagestringNoDenial reason when result=deny.
events[].descriptionstringConditionalRequired for user.define_outcome.
events[].rubricobjectConditionalRequired for user.define_outcome.
events[].reasonstringNoInterrupt reason for user.interrupt.
events[].is_errorbooleanNoError flag for tool result events.

Allowed input event types

user.message
user.interrupt
user.tool_confirmation
user.tool_result
user.custom_tool_result
user.define_outcome

Example request

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

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
dataarrayCreated Event objects after Forward filtering.

Errors

“-” in the table below means the response does not include error.code.
HTTPTypeCodeTrigger
503api_errorsession_materialization_busySession configuration refresh conflict; the response includes Retry-After: 1.
400invalid_request_errorinvalid_request_bodyThe request body cannot be parsed or its structure is invalid.
400invalid_request_errorinvalid_requestevents is empty, exceeds the count limit, or is missing a type.
400invalid_request_errorinvalid_eventEvent type or fields are invalid.
404not_found_errorsession_not_foundSession does not exist.
404not_found_error-The runtime cannot find the Session or an unresolved Pending Action.
409conflict_erroridentity_disabledThe Identity is disabled; new executions cannot start.
409invalid_request_errorsession_archivedSession is archived.
409invalid_request_error-The current Session is processing a Turn and cannot start a new Turn yet.
401authentication_error-Forward authentication failed.

Notes

  • On session_materialization_busy, back off according to Retry-After and retry with the original request body and Idempotency-Key (if present); check the Session state if conflicts persist.
  • Allowed input types are user.message, user.interrupt, user.tool_confirmation, user.tool_result, user.custom_tool_result, and user.define_outcome.
  • Disabling an Identity does not cancel accepted executions. While disabled, only tool confirmations or results matching real pending actions may be submitted, without new user messages. After re-enabling, a new turn can start in the same Session. See Disable an identity.
  • The response uses the filtered Forward Event object and does not expose raw runtime event JSON.

List session events

Stream session events