*MCP › Reference › Platform › Notes*

# Write a note on an entity

> Leaves a record on an entity of the account: why an order was rejected, how a repair is going.

> **Server annotation:** A note with `mentionedUserIds` notifies those Filmo users.

With `subRelatedDocumentType` and `subRelatedDocumentId` the note goes on a specific physical unit and not on the whole item. `mentionedUserIds` notifies those Filmo users. The notes of an entity are read with [`GET /api/v1/notes`](https://docs.filmo.io/rest-api/endpoint-reference/notes/list-the-notes-of-an-entity).

TOOL `filmo_notes_create` · `notes:write` · 120/min

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `relatedDocumentType` | string | Yes | Type of the entity the note is attached to. `item`, `contact`, `order`, `space`, `kit`, `vehicle`, `staff`, `service`, `collection`, `project`, `repairTicket`, `purchaseOrder`, `supplierInvoice` |
| `relatedDocumentId` | string | Yes | Identifier of that entity. |
| `content` | string | Yes | Note text. |
| `subRelatedDocumentType` | string | No | When the note is about a specific physical unit of the item. |
| `subRelatedDocumentId` | string | No | Identifier of that physical unit. Requires `subRelatedDocumentType`. |
| `subRelatedDocumentCode` | string | No | Code of the unit, so that it can be read in the note without resolving the id. |
| `mentionedUserIds` | string[] | No | Filmo users to notify. Each one receives a notification. |
| `idempotencyKey` | string | No | Idempotency key chosen by the client (a UUID is recommended). Repeating the same key with the same arguments within 24 h returns the stored response without executing again; with different arguments it responds 422. It is the safe way to retry after a network failure. |

## Result

On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`.

| Name | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier of the note. |
| `content` | string | Note text. |
| `relatedDocumentType` | string | Type of the entity the note is attached to; null if it is not attached. |
| `relatedDocumentId` | string | Identifier of that entity; null if the note is not attached. |
| `subRelatedDocumentType` | string | Type of the sub-entity; null if not applicable. |
| `subRelatedDocumentId` | string | Identifier of the sub-entity; null if not applicable. |
| `subRelatedDocumentCode` | string | Human-readable code of the sub-entity; null if not applicable. |
| `createdAt` | string<date-time> | Creation date in ISO 8601 UTC. |
| `updatedAt` | string<date-time> | Last modification date in ISO 8601 UTC. |

*Call · filmo_notes_create*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_notes_create",
    "arguments": {
      "relatedDocumentType": "item",
      "relatedDocumentId": "rela_8f2a1c",
      "content": "<content>"
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": {
      "id": "id_8f2a1c",
      "content": "<content>",
      "relatedDocumentType": "<relatedDocumentType>",
      "relatedDocumentId": "rela_8f2a1c",
      "subRelatedDocumentType": "<subRelatedDocumentType>",
      "subRelatedDocumentId": "subr_8f2a1c",
      "subRelatedDocumentCode": "<subRelatedDocumentCode>",
      "createdAt": "2026-09-01T08:00:00Z",
      "updatedAt": "2026-09-01T08:00:00Z"
    },
    "meta": {
      "idempotencyKey": "<the key you sent, or the one the server generated>",
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## Sample prompts

*Prompt*

```text
Leave a note on this order saying the customer will pick up at the north door.
```

## The same operation by REST

This tool runs [`POST /api/v1/notes`](https://docs.filmo.io/rest-api/endpoint-reference/notes/write-a-note-on-an-entity).

---

Canonical URL: https://docs.filmo.io/mcp/tools/notes/filmo-notes-create  
Last updated: 2026-10-25