Agents

Post Agent Chat

Say something to the agent and get its answer.

kind in the answer says which way the turn went: chat is a reply in message; work_item means the agent read the message as a job and STARTED it - work_item_id is the work item, and whether its workflow actually launched is in workflow_started.

Each turn runs a model and is charged. Omit session_id to start a new session.

post/agent/chat

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/agent/chat
  • Auth: HTTP bearer

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

messagestring

What you say to the agent. Required unless you attach a file.

session_idstring uuid nullable

Continue this session. Omit to start a new one; the answer carries its session_id.

client_turn_idstring uuid nullable

Your own id for this turn, so a retry is recognised as the same turn rather than said twice. Needs an existing session_id.

attachment_idsstring[]

Uploaded file ids to attach, each at most once.

subject_account_idstring nullable

Bind a NEW session to this account. Ignored for an existing one.

subject_campaign_idstring nullable

Bind a NEW session to this campaign. Ignored for an existing one.

modestring nullable

Bias the agent: web_search, deep_thinking or research. Left open, as the app leaves it: an unknown mode is ignored rather than refused.

mentionsobject[] nullable

@-mentions from POST /agent/mention-search, passed through as returned (id, category, display_name, ...).

pagestring nullable

Where the user is in your product, so 'this' and 'here' resolve.

Response

Successful Response

dataAgentConversationPayload required

An open envelope for the app's answer.

Open because the chat answer (kind, message, chips, sources, work_item_id, ...) and the oversight feed (approvals, blockers, autonomous_fixes, states, bounds) are both still growing, and a dropped field on an agent surface is one the caller does not know they lost.

Changes

No recorded changes to this operation across all 3 revisions of this API.