> ## Documentation Index > Fetch the complete documentation index at: https://docs.creao.ai/llms.txt > Use this file to discover all available pages before exploring further. # Post a room message > Post a message as yourself and start mentioned agents. ## OpenAPI ````yaml /developer-api/developer-v1.openapi.yaml post /v1/rooms/{room_id}/messages openapi: 3.1.0 info: title: CREAO CLI version: 1.0.0 description: | Create, update, and run personal CREAO agents from your backend through CREAO CLI with Account API keys. The `/v1` API uses stable `agent_id`, `conversation_id`, and `run_id` identifiers and is served from `developer.creao.ai`. servers: - url: https://developer.creao.ai description: Production security: - bearerAuth: [] - apiKeyQuery: [] tags: - name: Agents description: >- Create, list, get, update, and edit personal agents for the authenticated account. - name: Agent Memory description: >- Read, overwrite, and clear long-term memory (playbooks) for a personal agent. - name: Agent Files description: List, download, and delete files in a personal agent's skill file space. - name: Product Profile description: Once-per-account Super Agent persona and brand context. - name: Agent Runs description: >- Create, stream, fetch, and list runs for created personal agents. Super Agent rows are excluded. `usage.models` is present only for Super Agent–allowlisted accounts. - name: Super Agent description: >- Chat with CREAO Super Agent from your backend. Same public NDJSON render protocol as Agent Runs. Requires an allowlisted account. `usage.models` is present only for Super Agent–allowlisted accounts. - name: Account description: Read the calling account's platform-wallet balance and CREAO CLI spend. - name: Workspaces description: Create and list personal workspaces, and add or remove personal agents. - name: Workspace Files description: Upload, list, download, and delete files in a personal workspace. - name: Secrets description: Add, update, and list account secret keys. Values are write-only. - name: Skills description: Install, list, and enable account-level Agent Brain skills. - name: Rooms description: >- Read team rooms, post messages as the key's owner, and stream room events. The key acts as its owner. paths: /v1/rooms/{room_id}/messages: post: tags: - Rooms summary: Post a room message description: | Post Markdown as the key's owner, marked `origin: "api"`. `@Name` of an active member becomes a mention, and mentioned agents start unless `trigger_agents` is false. Unless `expand_shortcut` is false, text starting with `/name` sends the room's shortcut of that name, using its template at send time; a `/word` the room has no shortcut for posts as typed, and `//name` of a room shortcut posts `/name` (any other `//` text posts as typed). A retry with the same `client_msg_id` returns the original message with `200` and `duplicate: true`, before any `@Name` is resolved and without counting toward the per-room hourly post limit. operationId: postRoomMessage parameters: - $ref: '#/components/parameters/RoomId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostRoomMessageRequest' examples: mentionAgent: value: text: '@Researcher summarize the open launch blockers' client_msg_id: blockers-2026-10-09 bulkAlert: value: text: 'Deploy 1842 finished: 3 services updated' client_msg_id: deploy-1842 trigger_agents: false expand_shortcut: false responses: '200': description: A retry of an earlier post; nothing new was posted. content: application/json: schema: $ref: '#/components/schemas/PostRoomMessageResponse' '201': description: Posted. content: application/json: schema: $ref: '#/components/schemas/PostRoomMessageResponse' '400': description: >- Invalid request, an ambiguous `@Name`, a shortcut whose expansion is empty or too long, or another invalid message. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidInput: value: error: INVALID_INPUT ambiguousMention: value: error: ROOM_MENTION_AMBIGUOUS reason: >- "@Alex" matches several members; pass the intended member's id in `mentions` to pick them candidates: - member_id: 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b kind: user name: Alex - member_id: 6f7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c kind: agent name: Alex '401': $ref: '#/components/responses/AuthenticationRequired' '403': $ref: '#/components/responses/RoomsForbidden' '404': $ref: '#/components/responses/RoomNotFound' '409': description: >- The room is archived, or `client_msg_id` was used for something other than a post. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: archived: value: error: ROOM_ARCHIVED '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: RoomId: name: room_id in: path required: true schema: type: string format: uuid description: >- Room id. An id you cannot see answers `ROOM_NOT_FOUND`, like an unknown one. schemas: PostRoomMessageRequest: type: object additionalProperties: false required: - text properties: text: type: string minLength: 1 maxLength: 16000 description: >- Markdown. `@Name` of an active member becomes a mention. Unless `expand_shortcut` is false, a leading `/name` sends that room shortcut (an unknown name posts as typed) and a leading `//name` of a room shortcut posts `/name`; any other leading `//` posts as typed. client_msg_id: type: string minLength: 1 maxLength: 64 description: >- Idempotency key. A retry returns the stored message with `duplicate` true, whatever the room's members or limits since. The prefixes `a:` and `n:` are reserved. reply_to_seq: type: integer minimum: 0 description: >- Reply to this message. A message already in a message's replies puts the post in those replies; a top-level message leaves it in the main timeline (`root_seq` null). mentions: type: array maxItems: 50 description: >- Member ids to mention in addition to any `@Name` in `text`. An id among the members a shared `@Name` matches picks that member for the name. items: type: string format: uuid trigger_agents: type: boolean default: true description: >- False posts without waking any agent; mentions still render and people are notified. expand_shortcut: type: boolean default: true description: >- False posts `text` verbatim, with no shortcut expansion. Send false for text from another system that may start with a slash. PostRoomMessageResponse: type: object required: - message - duplicate - agent_invocations properties: message: $ref: '#/components/schemas/RoomMessage' duplicate: type: boolean agent_invocations: type: array description: Agents this post started; empty for a duplicate. items: type: object required: - agent_member_id - agent_name - invocation_id - status properties: agent_member_id: type: string format: uuid agent_name: oneOf: - type: string - type: 'null' invocation_id: type: string format: uuid status: type: string enum: - queued ErrorResponse: type: object additionalProperties: true required: - error properties: error: type: string description: Stable machine-readable error code. message: type: string description: Debug message. Do not rely on this field in production clients. available: type: number description: Available credits, when returned for credit errors. required: type: number description: Required credits, when returned for credit errors. retryAfterSeconds: type: integer description: Retry delay, when returned for hourly cap errors. reason: type: string description: >- A readable explanation on `400` and `409` room errors. Do not branch on it. candidates: type: array description: >- Members a `ROOM_MENTION_AMBIGUOUS` name matches. Resend with one of their ids in `mentions` to pick it. items: type: object properties: member_id: type: string format: uuid kind: type: string enum: - user - agent name: oneOf: - type: string - type: 'null' RoomMessage: type: object required: - seq - id - kind - sender - text - body - mentions - mentions_everyone - reply_to_seq - root_seq - created_at - edited_at - deleted - origin - agent_run_id - system_type - attachments - shortcut properties: seq: type: integer id: type: string format: uuid kind: type: string enum: - post - system sender: type: object required: - kind - member_id - name properties: kind: type: string enum: - user - agent - system member_id: oneOf: - type: string format: uuid - type: 'null' name: oneOf: - type: string - type: 'null' text: description: >- The message with mentions written as `@Name`; null when deleted or for system events. oneOf: - type: string - type: 'null' body: description: >- The stored message with its mention tokens; null when deleted or for system events. oneOf: - type: string - type: 'null' mentions: type: array items: type: object required: - member_id - name properties: member_id: type: string format: uuid name: oneOf: - type: string - type: 'null' mentions_everyone: type: boolean reply_to_seq: oneOf: - type: integer - type: 'null' root_seq: description: >- The top-level message whose replies this message is in; null in the main timeline. oneOf: - type: integer - type: 'null' created_at: type: string format: date-time edited_at: oneOf: - type: string format: date-time - type: 'null' deleted: type: boolean origin: description: Where a post came from. oneOf: - type: string enum: - web - mobile - desktop - api - agent - type: 'null' agent_run_id: description: Agent posts only. oneOf: - type: string - type: 'null' system_type: description: >- System events only, for example `member_joined` or `agent_run_failed`. oneOf: - type: string - type: 'null' attachments: type: array items: type: object required: - id - name - mime - size properties: id: type: string format: uuid name: type: string mime: type: string size: type: integer shortcut: description: The shortcut the post was sent with, as named when sent. oneOf: - type: object required: - id - name properties: id: type: string format: uuid name: type: string - type: 'null' responses: AuthenticationRequired: description: Missing, malformed, revoked, or unknown Account API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingKey: value: error: AUTHENTICATION_REQUIRED RoomsForbidden: description: > The rooms API is not enabled for this account (`ROOMS_API_NOT_ENABLED`), rooms are off in the requested team (`ROOMS_NOT_ENABLED`), the owner can read but not post (`ROOM_MEMBERSHIP_REQUIRED`, `ROOM_ACCESS_DENIED`), or the account is blocked (`ACCOUNT_BLOCKED`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: apiNotEnabled: value: error: ROOMS_API_NOT_ENABLED membershipRequired: value: error: ROOM_MEMBERSHIP_REQUIRED RoomNotFound: description: Unknown room, a room the key's owner cannot see, or a malformed id. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: value: error: ROOM_NOT_FOUND RateLimited: description: Account-level or IP-level rate limit exceeded. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: value: error: RATE_LIMITED ServiceUnavailable: description: Agent execution service was unavailable before the run was accepted. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unavailable: value: error: SERVICE_UNAVAILABLE securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: cr_sk description: Account API key from Developer Console. Keys start with `cr_sk_`. x-default: cr_sk_your_key_here apiKeyQuery: type: apiKey in: query name: creao-api-key description: | Account API key passed as a query parameter, for platforms that cannot set a custom Authorization header. The bearerAuth header takes precedence when both are present. x-default: cr_sk_your_key_here ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.