---
title: "Create Work Message"
method: POST
path: "/work/messages"
tags: ["Work"]
---

# Create Work Message

`POST /work/messages`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/work/messages`
- Auth: HTTP bearer

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.

## Headers

- `Idempotency-Key` string, nullable: Retry-safety key. Replaying one returns the ORIGINAL result with `duplicate: true` instead of writing twice. Omit it and the server mints a single-use key, which means a retried request writes again — send your own for anything you may retry.
- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- WorkMessageCreateRequest: 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.
  - `channel` string, required
  - `message` string, nullable
  - `document` object, nullable
  - `parentMessageId` string, nullable
  - `rootMessageId` string, nullable
  - `projectId` string, nullable
  - `mentionUserIds` string[]
  - `mentionAgentIds` string[]
  - `attachmentIds` string[]

## Response `201`

Successful Response

- ApiResponseWorkMessage
  - `data` WorkMessage, required: One stored Work message.
    - `id` string, nullable: Message id
    - `channel` string, nullable: Conversation address — a channel NAME or a direct-message id
    - `document` object, nullable: Rich-text document, normalized server-side
    - `text` string, nullable: Plain-text projection of the document
    - `author` object, nullable: Resolved author — always the authenticated principal, never a request field
    - `createdAt` string, nullable: Creation timestamp
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/89fc11143b70?raw)