> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genviral.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Post Editor Message

> Show a short message to the user watching a video project in the Genviral editor.

Posts a short message to the open Genviral web editor, where it appears live beside the timeline
together with each edit's step note. Use it to narrate your work as it happens: what you are about
to do, what you found (for example which clip and which seconds), what the next edit will change,
and a closing summary.

A message is narration only. It never changes the project, and its `updated_at` stays the same, so
the `expected_updated_at` you pass to your next [Apply Editor Ops](/api-reference/apply-editor-ops)
call remains valid and the open editor does not reload.

Messages are labelled in the editor with who sent them (Claude, ChatGPT, another MCP client, or
the API), derived from the credential. The editor keeps the newest 60 entries of a project's
activity.

## Idempotency

`Idempotency-Key` is required and is scoped to the API key (or MCP grant) that sends it.

* Retrying with the same key and the same body returns the first `posted_at` and shows the message
  once.
* Reusing a key with a different body returns `409 idempotency_key_reused`.

## Rate Limits

Messages are rate limited per account owner (120 per hour across all keys and workspaces). Over
the limit the request is refused with `429 rate_limited` and a `retry_after_seconds`.

## Path Parameters

<ParamField path="projectId" type="string (UUID)" required>
  The project id.
</ParamField>

## Body Parameters

<ParamField body="text" type="string" required>
  1 to 600 characters of plain text, trimmed. Line breaks are allowed; other control characters
  and markdown formatting are not meant for this field. Keep it to 1-3 conversational sentences in
  the user's language.
</ParamField>

## Response

Returns `201` with the project id and when the message was posted.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://www.genviral.io/api/partner/v1/editor/projects/b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f/messages \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --header 'Idempotency-Key: 5a1c9e72-0d4b-4f3a-9b6e-7c2d1e8f4a90' \
    --data '{
      "text": "IMG_8103 has 17 s of sky after the phone tipped over. Cutting that first."
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 201,
    "message": "Editor message posted",
    "data": {
      "project_id": "b1d4e8f2-3a5c-4d7e-8f90-1a2b3c4d5e6f",
      "posted_at": "2026-10-02T12:04:12.000Z"
    }
  }
  ```
</ResponseExample>

## Error Responses

* `400 invalid_json` - request body is not valid JSON
* `400 invalid_request` - `Idempotency-Key` header is missing or longer than 255 characters
* `401` - authentication failed (missing/invalid/revoked token)
* `404 project_not_found` - the project does not exist in the key scope
* `409 idempotency_key_reused` - this `Idempotency-Key` was already used with a different body
* `409 request_in_progress` - an identical request with this key is still being processed; retry shortly
* `422 invalid_payload` - body failed validation (see `issues`)
* `429 rate_limited` - the hourly message allowance is spent; retry after `retry_after_seconds`
* `503 provider_unavailable` - the rate limiter could not answer; retry shortly


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.