--- id: reference.create-note title: Create a note summary: Preview an API operation page built from a small, fictional OpenAPI file. type: api-reference area: api subarea: api-examples canonical: /example-api/create-note --- # Create a note > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json) Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt) Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Examples > Example Notes API > Create a note **Updated: 2026-10-19.** > Fictional API example. This page demonstrates documentation features; its operations do not describe a live service. This page is a live example of an API reference generated by Shoalrun. The [source OpenAPI file](https://www.shoalrun.com/api/notes/production/current/openapi.yaml) defines one fictional operation; this introduction is authored in MDX. The build combines them into the operation details below and the example panel on the right. > **Example only:** The Notes API is fictional. These requests are examples, not calls to a live service. OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/notes-create-2f1dbbdb63898bb3e6946fd275e1f38452bda5b95569e75144d6fa72b711b892.json). ## POST /notes Create a note Save a short note in this fictional API. ### Servers `https://api.example.test` ### Request body Required. #### application/json object 1 property - `text` `string` **required** maxLength: 280 The note to save. ##### Example: A greeting Key: greeting. Location: request; application/json. Authored in OpenAPI. ```json { "text": "Hello from Shoalrun!" } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"Hello from Shoalrun!"}' ``` ##### Example: A reminder Key: reminder. Location: request; application/json. Authored in OpenAPI. ```json { "text": "Review the release notes." } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"Review the release notes."}' ``` ##### Example: A question Key: question. Location: request; application/json. Authored in OpenAPI. ```json { "text": "Is the preview ready?" } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"Is the preview ready?"}' ``` ##### Example: A status update Key: update. Location: request; application/json. Authored in OpenAPI. ```json { "text": "The build passed." } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"The build passed."}' ``` ##### Example: A handoff Key: handoff. Location: request; application/json. Authored in OpenAPI. ```json { "text": "Casey owns the next review." } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"Casey owns the next review."}' ``` ##### Example: A meeting note Key: meeting. Location: request; application/json. Authored in OpenAPI. ```json { "text": "Discuss the API response shape." } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"Discuss the API response shape."}' ``` ##### Example: A follow-up Key: followup. Location: request; application/json. Authored in OpenAPI. ```json { "text": "Check the example links." } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"Check the example links."}' ``` ##### Example: A short label Key: label. Location: request; application/json. Authored in OpenAPI. ```json { "text": "Needs review" } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"Needs review"}' ``` ##### Example: Unicode text Key: unicode. Location: request; application/json. Authored in OpenAPI. ```json { "text": "Café notes" } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"Café notes"}' ``` ##### Example: A completion note Key: completion. Location: request; application/json. Authored in OpenAPI. ```json { "text": "Documentation published." } ``` Example request (cURL): ```bash curl --request POST \ --url 'https://api.example.test/notes' \ --header 'Content-Type: application/json' \ --data-raw '{"text":"Documentation published."}' ``` ### Responses #### 201: Created `application/json` The saved note. A saved note with its author, labels, and display metadata. 7 properties - `id` `string` **always present** The generated note ID. - `text` `string` **always present** maxLength: 280 The saved text. - `createdAt` `string` **always present** format: date-time When the note was created. - `archivedAt` `string` **always present** **nullable** format: date-time When the note was archived, or null while active. - `author` `object` **always present** The person who created the note. 2 properties - `id` `string` **always present** The author's user ID. - `displayName` `string` **always present** The author's display name. - `tags` `list of string` **may be absent** Labels used to organize the note. Array items: string - `metadata` `object` **may be absent** Optional display information for a note. 2 properties - `source` `string` **may be absent** Where the note came from. - `pinned` `boolean` **may be absent** Whether the note stays at the top. ##### Example: Created release note Key: saved. Location: response 201; application/json. Authored in OpenAPI. An active note with a nested author, two labels, and optional display metadata. ```json { "id": "note_123", "text": "Review the release candidate.", "createdAt": "2026-10-18T09:30:00Z", "archivedAt": null, "author": { "id": "usr_42", "displayName": "Morgan Lee" }, "tags": [ "release", "review" ], "metadata": { "source": "release-checklist", "pinned": true } } ``` ## Related guides - [Prepare a note request](https://www.shoalrun.com/example-api/write-note.md) — Prepare a fictional note payload and follow its linked operation contracts.