---
title: "Create Message"
method: POST
path: "/v2/communication/"
tags: ["v2 - Communication"]
---

# Create Message

`POST /v2/communication/`

## Request

- Base URL: `https://api.jubjubapp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.jubjubapp.com/v2/communication/`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string, nullable
- `Authorization` string
- `X-JubJub-Service-Key` string
- `X-JubJub-Agent-Key` string
- `X-JubJub-Platform-Key` string
- `Origin` string
- `Referer` string
- `X-JubJub-Trial-Token` string

## Request body

- CreateMessageRequest: Request to create a new communication message.
  - `scope_type` string, required: Scope type: team, workspace, content, media, collection
  - `scope_id` string, required: ID of the scoped entity
  - `body` string, required
  - `mentions` string[]: People mentioned, as member_refs (from a member list or a message's mention_profiles). A raw profile ID is still accepted from older clients.
  - `parent_message_id` string, nullable: Reply-to message ID
  - `message_type` string: comment, decision, status_change, system
  - `timecode_seconds` integer, nullable: Optional video timecode (seconds, >=0). Only valid when scope_type=='media'.
  - `decision_type` string, nullable: approval, review, sign_off
  - `author_type` string: human, agent, system
  - `author_service_id` string, nullable
  - `idempotency_key` string, nullable
  - `origin` string, nullable
  - `metadata` object, nullable: Arbitrary client metadata (e.g. video timestamp, annotation)
  - `collection_id` string, nullable: Collection context for media-scope auth fallback

## Response `201`

Successful Response

- MessageResponse: Full message response. People are identified by `author`, `mention_profiles` and `resolved_by_profile` (public profiles with member_refs). The raw `author_profile_id` and `resolved_by` are present only when they are the caller's own ID (or the caller is a platform admin); otherwise null.
  - `message_id` string, required
  - `scope_type` string, required
  - `scope_id` string, required
  - `author_profile_id` string, nullable
  - `author` PersonView: Another person as anyone may see them (founder's rule, 2026-09-25). `member_ref` is opaque and scoped to the message's context: the workspace for workspace, content and media scopes, the team for a team scope. Post it back in `mentions` to mention this person. Never a profile ID or email; `profile_id` is filled only for a JubJub platform admin.
    - `member_ref` string, nullable
    - `display_name` string, required
    - `avatar_url` string, nullable
    - `handle` string, nullable
    - `is_you` boolean
    - `role` string, nullable
    - `via_team` string, nullable
    - `profile_id` string, nullable
  - `author_type` string, required
  - `author_service_id` string, nullable
  - `body` string, required
  - `mentions` string[]: member_refs of the people mentioned
  - `mention_profiles` PersonView[]
    - `member_ref` string, nullable
    - `display_name` string, required
    - `avatar_url` string, nullable
    - `handle` string, nullable
    - `is_you` boolean
    - `role` string, nullable
    - `via_team` string, nullable
    - `profile_id` string, nullable
  - `workspace_id` string, nullable
  - `timecode_seconds` integer, nullable
  - `version` integer, nullable
  - `parent_message_id` string, nullable
  - `thread_root_id` string, nullable
  - `message_type` string, required
  - `decision_type` string, nullable
  - `decision_status` string, nullable
  - `resolution` string, nullable
  - `origin` string, nullable
  - `event_version` integer
  - `metadata` object, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, nullable
  - `edited_at` string, date-time, nullable
  - `deleted_at` string, date-time, nullable
  - `resolved_at` string, date-time, nullable
  - `resolved_by` string, nullable
  - `resolved_by_profile` PersonView: Another person as anyone may see them (founder's rule, 2026-09-25). `member_ref` is opaque and scoped to the message's context: the workspace for workspace, content and media scopes, the team for a team scope. Post it back in `mentions` to mention this person. Never a profile ID or email; `profile_id` is filled only for a JubJub platform admin.
    - `member_ref` string, nullable
    - `display_name` string, required
    - `avatar_url` string, nullable
    - `handle` string, nullable
    - `is_you` boolean
    - `role` string, nullable
    - `via_team` string, nullable
    - `profile_id` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/jubjubapp/apis/jubjub-api.md) - [All operations](https://skmtc.dev/jubjubapp/apis/jubjub-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jubjubapp/apis/jubjub-api/revisions/353157b296f2?raw)