Note

Type Schema name Note, addressed at /api/v1/entity/notes. The slug is neither case nor plural sensitive, and only an unknown name is refused.

GET /entity/notes  -> 200      GET /entity/Note   -> 200
GET /entity/note   -> 200      GET /entity/notess -> 404 "Entity type 'notess' does not exist."

Project-scoped. Note.project is an editable entity field, valid_types: ['Project'], and a create without it is refused. An unfiltered _search returns notes from every project, so filter on project.

Identity subject, display name Subject, data_type: text, the only field flagged mandatory and none is flagged unique. A client shows it as the note's title. The body is content, display name Body, also text; Task.content is display name Task Name and is Task's identity (entity_types/Task), so the same field name is a title on one type and a body on the other.

cached_display_name copies neither: it is subject alone when content is empty and "<subject> - <content>" when both are set. A PUT to it returns 200 and changes nothing (probe 004).

Create POST /entity/notes, Content-Type: application/json. project is the whole contract and the field flagged mandatory is optional, as on Asset, Task and Version (probe 012).

An omitted subject is not auto-filled, unlike Asset.code and Task.content: the row has no title. The 201 echoes the server's defaults, so read them off the response:

{"cached_display_name": "", "sg_status_list": "opn", "publish_status": "published",
 "read_by_current_user": "unread", "created_at": "...", "updated_at": "...",
 "reply_content": "Warning: If you see this displayed in the UI, it means the widget is not
  respecting grid_column = false."}

user and created_by both hold the authenticating script's ApiUser, and every link field is [].

Links Written and read as described in field_types/entity and field_types/multi_entity.

note_links attaches a Note to the thing it is about. Task is absent: a Note about a Task goes in the separate tasks field. On the probed site valid_types holds 28 entries, 26 stock and two CustomEntityNN:

Asset, Booking, Camera, Contract, Cut, Department, Episode, Group, Launch, Level, MocapPass,
MocapSetup, MocapTake, MocapTakeRange, Performer, Playlist, Reel, Routine, Scene, Sequence,
ShootDay, Shot, Slate, SourceClip, TaskTemplate, Version

Search "notes about X" through the link: it filters although it cannot be read back (probe 016), and the path names the target type, which decides the name field (probe 071).

The list is not enforced either, and creates sending [{"type": "Project", ...}] and [{"type": "HumanUser", ...}] both returned 201 and read the link back. Starting from [Shot, Asset]:

Threading The link is stored on the Reply, in Reply.entity. Note.replies is the reverse view, and writing it destroys rows rather than unlinking them. entity_types/Reply covers the other end.

Attachments An Attachment links in the same call that creates the Note; no second pass is needed. POST /entity/attachments {"project": {...}} returns 201 for an empty row, and probe 014 uploads a file.

Status sg_status_list, a status_list, holding a raw code and never a label. Read a project's usable set as valid_values minus hidden_values, which writes do not enforce (field_types/status_list); the vocabulary and both lists are site configuration.

GET /schema/Note/fields/sg_status_list?project_id=<pid>
  -> properties.valid_values.value, .hidden_values.value, .display_values.value

default_value applies when the key is omitted on create, so a Note is never statusless. The open_notes_count rollup on other types counts Notes whose status is in the site's open set and can be neither filtered nor sorted (field_types/summary).

Read state read_by_current_user holds "read" or "unread" per authenticated identity and is in no schema response: GET /schema/Note/fields returns 33 fields without it, and GET /schema/Note/fields/read_by_current_user answers 200 with data: null (probe 068).

Traps

• client_note cannot be set over the API, on create or after. Every update answers 400 API update() Note.client_note is editable on create only. A client-facing Note over REST is sg_note_type: "Client", an editable list, and nothing else; it leaves client_note false (probe 069).
• A bare replies: [] write deletes the Reply rows. Trimming that list the way a client trims any other multi_entity field destroys the replies, with nothing at the id after. Keep it out of a PUT.
• A bare list written to note_links replaces the set, so appending one link with [{"type": "Shot", "id": N}] drops every other thing the Note was about (field_types/multi_entity).
• subject is optional, not auto-filled and not unique: a request that dropped its payload creates a real titleless Note, and two Notes in one project may share a subject. Key on id.
• meta is editable on create only. Seed it in the POST or never: every later PUT answers 400 API update() Note.meta is editable on create only. (field_types/jsonb).