Create Work Message
POST /work/messages
Post one message into a conversation this credential may write to.
channel addresses the conversation — a channel name or id. Send either
message (plain text) or document (a rich-text document, normalized
server-side so a hostile link never reaches storage), plus optional
attachmentIds, mentionAgentIds and thread parents.
403 when the caller is not a member of the channel — an organisation
credential holds a seat in the built-in channels and nowhere else, so that
is where it can post. 404 when no such conversation exists.
Mentioning an agent starts an agent turn in the background, which is how a
message gets answered; the send returns as soon as the message is stored.
The author is resolved from the authenticated principal and the body cannot
express one — author, actor_id and org_id are refused outright.
Billing: conditional. A message with no agent mention spends nothing. One
that mentions an agent starts a turn that spends credits (token-based, charged
after the agent answers, to the target client org for an agency key). The
response carries agentTurn with an estimatedCredits quote; the final
charge may differ. Send X-G8-Confirm-Spend to record that a human accepted
the spend; it is optional today.
402 (plain message, nothing posted) only when this message mentions an agent
and the client organization that would pay has ALREADY used its monthly credit cap.
Every other case, including no cap, an unenrolled org or a cap we cannot read, is
unchanged.
Authorizations
Parameters
Header Parameters
Request Body required
One message a person is sending into a Work channel.
Carries what is being said and where — never who is saying it. The author,
the organization and the signing identity all come from the authenticated
session in work/router.py; Idempotency-Key comes from the header.
object
Responses
201
Successful Response
object
A message just posted, plus whether it started a credit-spending agent turn.
object
What a send costs, declared on the response of the call that started it.
The charge itself is made after the agent has answered, in token terms, so
this is an ESTIMATE: estimatedCredits is a quote, and the final charge
may differ (a long turn costs more).
object
True when that turn spends credits; false for a send nobody answers
Estimated credits for the turn, 0 when not billable. Final charge may differ
Most ONE model call can cost (the per-call cap). A turn that uses tools makes several calls, each charged, so the whole turn can exceed it
True when this send asked for an agent turn (it mentions an agent)
object
object
Whether there are more pages
Items per page
Current page number (1-indexed)
Total number of items
422
Validation Error