> For the complete documentation index, see [llms.txt](https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/nimbus-notes-api/nimbus-notes-api-reference-documentation-sample.md). # Nimbus Notes API - Reference Documentation - Sample *Contractor-style reference documentation for a fictional REST API, focused on developer experience, accuracy, and real-world constraints.* Nimbus Notes is a cloud-based note-taking service that allows users to create, organize, tag, and share notes. * **Base URL:** `https://api.nimbusnotes.io/v1` * **Format:** JSON over HTTPS * **Auth:** Bearer token (OAuth-style, but simplified) * **Rate limit:** 1,000 requests/hour per token #### Getting Started * Step 1: Get an access token using `POST /auth/token` * Step 2: Verify authentication by calling `GET /me` * Step 3: Create your first note using `POST /notes` ### GET Get current user `https://api.nimbusnotes.io/v1/me` All requests (except `POST /auth/token`) require a Bearer token. **Getting an Access Token** Use `POST /auth/token` with your email and password to retrieve a token. Tokens expire after 24 hours. **Possible responses** * `200 OK` - User retrieved successfully * `401 Unauthorized` - Invalid or missing token **Example Request** *Current authenticated user* ```curl curl --location 'https://api.nimbusnotes.io/v1/me' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` **Example Response** ```json { "id": "usr_8f29d", "email": "alex@nimbus.io", "name": "Alex Rivera", "created_at": "2024-05-04T08:35:24.984Z" } ``` Content-Type: `application/json` ### POST Create a note `https://api.nimbusnotes.io/v1/notes` You must provide a title and content when creating a note. You can pin the note on creation, and add tags. Please note that the maximum lenght of a note is 10,000 characters. #### Fields | Field | Type | Explanation | | ----------- | -------------- | ------------------------------------------------------------------- | | `title` | string | Required. Your note's title. | | `content` | string | Required. The note's content, with a maximum of 10,000 characters. | | `tags` | array\[string] | Optional tags to classify your notes. Case insensitive. | | `is_pinned` | boolean | Optional. Defaults to false. A user may have up to 50 pinned notes. | #### Responses * `201 Created` — Note created successfully * `400 Bad Request` — Missing title or content * `400 Bad Request` — Content exceeds 10,000 characters * `401 Unauthorized` — Invalid or missing token **Example Request** ```json { "title": "Meeting Notes", "content": "Discuss Q1 roadmap and hiring plan.", "tags": ["meetings", "work"], "is_pinned": false } ``` **Example Request** *Note created* ```curl curl --location 'https://api.nimbusnotes.io/v1/notes' \ --data '{ "title": "Meeting Notes", "content": "Discuss Q1 roadmap and hiring plan.", "tags": ["meetings", "work"], "is_pinned": false } ' ``` **Example Response** ```json { "id": "note_a92kf", "title": "Meeting Notes", "content": "Discuss Q1 roadmap and hiring plan.", "tags": [ "meetings", "work" ], "is_pinned": false, "created_at": "2026-01-10T09:14:31Z", "updated_at": "2026-01-10T09:14:31Z" } ``` Content-Type: `application/json` ### PATCH Update a note `https://api.nimbusnotes.io/v1/notes/:note_id` Update one or more fields of an existing note. * Tag names are case-insensitive. * You can have a maximum of 50 pinned notes. In the request body, enter the field you would like to modify. Accepted fields are: `title`, `content`, `tags`, `is_pinned` **Responses** * `200 OK` — Updated note * `404 Not found` — Note not found * `401 Unauthorized` — Invalid or missing token **Example Request** ```curl curl --location --request PATCH 'https://api.nimbusnotes.io/v1/notes/note_a92kf' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{ "content": "Discuss Q1 roadmap and hiring plan. Follow up with Mark" }' ``` **Example Response** ```json { "id": "note_a92kf", "title": "Meeting Notes", "content": "Discuss Q1 roadmap and hiring plan. Follow up with Mark", "tags": [ "meetings", "work" ], "is_pinned": false, "created_at": "2026-01-10T09:14:31Z", "updated_at": "2026-01-15T08:20:55Z" } ``` Content-Type: `application/json` ### GET List notes `https://api.nimbusnotes.io/v1/notes` Returns a paginated list of notes (20 per page by default). Each item in the response contains the full note object. To retrieve the next page of results, pass the `next_cursor` value as the `cursor` query parameter in your next request. **Responses** * `200 OK` — Notes retrieved successfully * `401 Unauthorized` — Invalid or missing token * `400 Bad Request` — Invalid query parameter **Example query** ```curl curl --location 'https://api.nimbusnotes.io/v1/notes?tag=work&pinned=false&limit=10%27' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` **Example Request** ```curl curl --location 'https://api.nimbusnotes.io/v1/notes?tag=string&pinned=boolean&limit=number&cursor=string' ``` **Example Response** ```json { "data": [ { "id": "note_a92kf", "title": "Meeting Notes", "content": "Discuss Q1 roadmap and hiring plan.", "tags": [ "meetings", "work" ], "is_pinned": false, "created_at": "2026-01-10T09:14:31Z", "updated_at": "2026-01-10T09:14:31Z" }, { "id": "note_a85ko", "title": "Q1 Roadmap", "content": "Liaise with Christine", "tags": [ "reminders", "work" ], "is_pinned": true, "created_at": "2026-01-17T09:14:31Z", "updated_at": "2026-01-17T09:14:31Z" } ], "next_cursor": "eyJpZCI6Im5vdGVfYjMifQ==" } ``` Content-Type: `application/json` ### DELETE Delete a note `https://api.nimbusnotes.io/v1/notes/:note_id` Allows the user to delete an existing note. Deleting a note marks it as deleted. The note can be recovered for up to 30 days before being permanently removed. **Responses** * `200 OK` — Note deleted successfully * `401 Unauthorized` — Invalid or missing token * `404 Not Found` — Note does not exist **Example Request** `https://api.nimbusnotes.io/v1/notes/note_a92kf` ```curl curl --location --request DELETE 'https://api.nimbusnotes.io/v1/notes/string' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` **Example Response** ```json { "deleted": true } ``` Content-Type: `application/json` ### POST Share a note `https://api.nimbusnotes.io/v1/notes/:note_id/share` Share a note with another user. **Request body** | Field | Type | | ------------ | ------ | | `email` | string | | `permission` | string | Permission types include: * `read` * `comment` * `edit` A successful request returns an empty response with a success status code. **Example Request** ```json { "email": "teammate@nimbus.io", "permission": "read" } ``` **Example Request** *Note shared successfully* ```curl curl --location 'https://api.nimbusnotes.io/v1/notes/string/share' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --data-raw '{ "email": "alex@nimbus.io", "permission": "comment" }' ``` **Example Response** This request doesn't return any response body. ### GET List all tags `https://api.nimbusnotes.io/v1/tags` Returns a list of tags with usage counts. **Example Request** *List of tags with usage counts* ```curl curl --location 'https://api.nimbusnotes.io/v1/tags' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` **Example Response** ```json { "tags": [ { "name": "work", "count": 12 }, { "name": "personal", "count": 5 } ] } ``` Content-Type: `application/json` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/nimbus-notes-api/nimbus-notes-api-reference-documentation-sample.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.