---
title: "Create a notebook"
method: POST
path: "/notes/~/v1/notebooks"
---

# Create a notebook

`POST /notes/~/v1/notebooks`

First-class convenience endpoint — flat body, no discriminated
union. Equivalent to submitAction with a create-notebook action.
Returns the new notebook's summary (incl. the slugified flag).

## Request body

- object
  - `title` string, required

## Response `200`

Created — response body is type `notebook`

- Response
  - `requestId` string, required — Canonical Hoon `@uv` (base-32 with `.` separators every 5 chars from the right, prefixed `0v`). A correlation id for the request. OPTIONAL on POST: if you omit it (or send something that isn't a valid `@uv`), the server mints one and returns it in the response. You only need to supply your own if you intend to poll `GET /request/{requestId}` or subscribe to the SSE request stream — for the common case (read the held-open POST response inline) you can leave it out entirely.
  - `body` union, required
    - ResponseOk
      - `type` 'ok', required
      - `response` union, required
        - RSnapshot
          - `type` 'snapshot', required
          - `host` string, required
          - `flagName` string, required
          - `visibility` 'public' | 'private', required
        - RUpdate
          - `type` 'update', required
          - `host` string, required
          - `flagName` string, required
          - `time` integer, required — Unix seconds when the host applied the change.
          - `update` union, required
            - UNbCreated
              - …
            - UNbUpdated
              - …
            - UNbDeleted
              - …
            - UNbVisibilityChanged
              - …
            - UMemberJoined
              - …
            - UMemberLeft
              - …
            - UInviteReceived
              - …
            - UInviteRemoved
              - …
            - UFolderUpdate
              - …
            - UNoteUpdate
              - …
    - ResponseNoChange
      - `type` 'no-change', required
    - ResponseNotebook — Returned by `create-notebook` — the new notebook's summary so the caller learns the slugified flag + metadata without a follow-up read.
      - `type` 'notebook', required
      - `notebook` NotebookSummary, required
        - `host` string, required
        - `flagName` string, required
        - `notebook` Notebook, required
          - `id` integer, required
          - `title` string, required
          - `rootFolderId` integer, required — Id of the notebook's root folder. Pass this as `parent` when creating a folder/note at the top level. Equal to `id + 1`.
          - `createdBy` string, required
          - `createdAt` integer, required — Unix seconds
          - `updatedAt` integer, required
          - `updatedBy` string, required
        - `visibility` 'public' | 'private', required
    - ResponseApiKey — Returned by `regenerate-api-key` (new key) and `clear-api-key` (apiKey: null). `apiKey` is the value to send as `X-Api-Key`.
      - `type` 'api-key', required
      - `apiKey` string, nullable, required
    - ResponseError
      - `type` 'error', required
      - `errorType` 'not-authorized' | 'not-found' | 'invalid-name' | 'conflict' | 'request-too-large' | 'unknown', required — Structured failure mode. `conflict` corresponds to an `expectedRevision` mismatch on a note update. Today most host-side crashes surface as `unknown` (raw nack); future work will route revision-mismatch and visibility errors to their typed variants.
      - `message` string[], required — Hoon `tang` rendered as JSON strings. Empty for now.
    - ResponsePending
      - `type` 'pending', required
      - `status` 'sending' | 'acked' | 'nacked', required — Where the cross-ship poke stood when the timeout fired. `sending` = no poke-ack yet, `acked` = host accepted but no response-update yet, `nacked` = host crashed (a terminal `error` body would normally have followed; if you see this, the timeout beat the nack delivery).

## Other responses

- `400` — Missing/invalid title
- `401` — Unauthorized

---

[API](https://skmtc.net/tloncorp/apis/notes-v1-http-api.md) · [All operations](https://skmtc.net/tloncorp/apis/notes-v1-http-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tloncorp/notes-v1-http-api/versions/9beef8e14823/schema)