# addNote

mutation · in the family [Work and notes](/reference/work-and-notes/)

## What it does

Attach a note (optionally with files) to any record — an order, a product, a customer.

Append ONE immutable note to ANY same-tenant construct: the target gates existence + same-rootId (its type stamps onto the row); parentNoteId threads ONE level (a reply-to-a-reply refuses naming the root); links ≤8 scheme-fenced; attachmentIds bind the caller's own PRIOR upload-mints — the commit HeadObject-verifies each blob, composes the IMMUTABLE META, flips the pending tag, stamps the wallet counter, and mints the BLOBBOOK rows, ALL in ONE transaction. The acting User stamps as the author. Requires the unrestricted capability. Template class (universal staff work — hand-derived v29).

## What happens

Notes are permanent, threaded one level, and travel with the record; attachments are virus-screened where required.

## Careful

Notes cannot be edited or deleted — write what you would be comfortable seeing in an audit.

## Who may call it

Capability area: **Work and notes** — Tasks, notes, messages, dashboards and the everyday tools every staff member keeps.

- Owner
- System Administrator
- Manager
- Associate Manager
- Warehouse Associate
- Sales Associate
- Cashier
- An API key whose scope allows `api:addNote`

## Arguments

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `input` | [NewNoteInput](/types/NewNoteInput/) `NewNoteInput!` | yes | No further notes. |

## Returns

[Note](/types/Note/) `Note!` — One generic note on ANY same-tenant construct. Internal-only in v1 (no consumer face — CsCase owns that lane).

## Example request

```graphql
mutation ExampleAddNote($input: NewNoteInput!) {
  addNote(input: $input) {
    id
    type
    caption
    status
    parentId
    rootId
    createdAt
    updatedAt
    revisionNum
    revision
    targetType
    authorId
    parentNoteId
    title
    kind
    body
    labelIds
    taskId
  }
}
```

Variables:

```json
{
  "input": {
    "targetConstructId": "01900000-0000-7000-8000-79e077380000",
    "targetType": "<target type>",
    "body": "Restock before the weekend.",
    "parentNoteId": "01900000-0000-7000-8000-907baa100000"
  }
}
```

Send it with the envelope naming the version: `"extensions": {"at": {"version": {"name":"genesis","number":0}}}`.

## Example response

```json
{
  "data": {
    "addNote": {
      "id": "01900000-0000-7000-8000-37386ae00000",
      "type": "<type>",
      "caption": "Blue jeans",
      "status": "<status>",
      "parentId": "01900000-0000-7000-8000-065235280000",
      "rootId": "01900000-0000-7000-8000-a093dd800000",
      "createdAt": "2027-01-31T00:00:00.000Z",
      "updatedAt": "2027-01-31T00:00:00.000Z",
      "revisionNum": 1,
      "revision": "01900000-0000-7000-8000-b7960e180000",
      "targetType": "<target type>",
      "authorId": "01900000-0000-7000-8000-0046e40b0000",
      "parentNoteId": "01900000-0000-7000-8000-907baa100000",
      "title": "Blue jeans",
      "kind": "<kind>",
      "body": "Restock before the weekend.",
      "labelIds": [
        "01900000-0000-7000-8000-a235e7410000"
      ],
      "taskId": "01900000-0000-7000-8000-6ceba5410000"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}
```

## Errors this call can answer

- `VALIDATION/INVALID` — Something in the request is not valid. ([VALIDATION](/errors/VALIDATION/))
- `AUTHN/REQUIRED` — Sign in to do this. ([AUTHN](/errors/AUTHN/))
- `AUTHZ/FORBIDDEN` — Your role does not allow this action. ([AUTHZ](/errors/AUTHZ/))
- `RATE_LIMIT/THROTTLED` — Too many requests in a short time. ([RATE_LIMIT](/errors/RATE_LIMIT/))
- `NOT_FOUND/*` — That record could not be found. ([NOT_FOUND](/errors/NOT_FOUND/))
- `CONFLICT/*` — The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. ([CONFLICT](/errors/CONFLICT/))
- `VALIDATION/VERSION_REQUIRED` — The request did not say which app version it came from. ([VALIDATION](/errors/VALIDATION/))

## Used in

- [Give the team its work — tasks, labels, hand-offs](/use-cases/give-the-team-its-work/)