REST API v1

API Reference

Manage NoteSmith documents programmatically. All endpoints require an API key created in your account settings.

Authentication

All requests must include your API key as a Bearer token in the Authorization header. API keys are created and managed in Settings → API Keys. Each key is shown only once at creation — store it securely.

http

Authorization: Bearer ns_your_key_here

Keep your key secret. Treat it like a password. Do not commit it to version control or expose it client-side. You can revoke a key at any time from settings.

Base URL

All API endpoints are relative to the following base URL:

text

https://notesmith.io/api/v1

Errors

The API uses conventional HTTP status codes. Errors return JSON with an error field describing what went wrong.

Code	Meaning
200	OK — request succeeded
201	Created — resource was created
400	Bad Request — missing or invalid parameters
401	Unauthorized — API key missing or invalid
403	Forbidden — your key does not have access to this resource
404	Not Found — resource does not exist or was deleted
500	Server Error — something went wrong on our end

json

// Error response shape
{
  "error": "workspaceId query param required"
}

The document object

Most endpoints return a document object or an array of them.

json

{
  "id":          "cma1b2c3d4e5f6g7h8i9j0",
  "title":       "Q3 Planning Notes",
  "icon":        "📋",
  "workspaceId": "cma0z9y8x7w6v5u4t3s2r1",
  "folderId":    null,
  "content":     "Plain-text representation of the document body.",
  "createdAt":   "2025-06-01T10:00:00.000Z",
  "updatedAt":   "2025-06-15T14:32:00.000Z",
  "createdBy": {
    "id":    "usr_abc123",
    "name":  "Jane Smith",
    "email": "[email protected]"
  }
}

Note: content is only returned by the Get Document endpoint. List and Create return metadata only.

Documents

Create, read, and update documents in your workspaces.

GET/api/v1/docs

List documents

Returns a paginated list of documents in a workspace. You must be a member of the workspace.

Query parameters

Parameter	Type	Description
workspaceIdrequired	string	The ID of the workspace to list documents from.
limit	integer	Max documents to return. Default `50`, max `100`.
offset	integer	Number of documents to skip for pagination. Default `0`.

Example request

bash

curl https://notesmith.io/api/v1/docs?workspaceId=cma0z9y8x7w6v5u4t3s2r1 \
  -H "Authorization: Bearer ns_your_key_here"

Response

json

{
  "docs": [
    {
      "id":          "cma1b2c3d4e5f6g7h8i9j0",
      "title":       "Q3 Planning Notes",
      "icon":        "📋",
      "folderId":    null,
      "createdAt":   "2025-06-01T10:00:00.000Z",
      "updatedAt":   "2025-06-15T14:32:00.000Z",
      "createdBy":   { "id": "usr_abc", "name": "Jane Smith", "email": "[email protected]" }
    }
  ],
  "total":  42,
  "limit":  50,
  "offset": 0
}

POST/api/v1/docs

Create document

Creates a new document in a workspace. You must have at least Member role (not Viewer) in the workspace. Optionally supply Markdown content — it will be converted automatically.

Request body

Field	Type	Description
workspaceIdrequired	string	The workspace to create the document in.
title	string	Document title. Defaults to `"Untitled"` if omitted. Max 500 characters.
content	string	Initial document body as plain Markdown. Converted to the NoteSmith rich-text format on write.
folderId	string	Place the document inside this folder. Omit or pass `null` for the workspace root.
icon	string	A single emoji used as the document icon (e.g. `"📋"`).

Example request

bash

curl -X POST https://notesmith.io/api/v1/docs \
  -H "Authorization: Bearer ns_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title":       "My Doc",
    "workspaceId": "cma0z9y8x7w6v5u4t3s2r1",
    "content":     "# Hello\n\nThis is the document body.",
    "icon":        "📝"
  }'

Response 201 Created

json

{
  "id":        "cma1b2c3d4e5f6g7h8i9j0",
  "title":     "My Doc",
  "icon":      "📝",
  "folderId":  null,
  "createdAt": "2025-06-15T14:00:00.000Z",
  "updatedAt": "2025-06-15T14:00:00.000Z"
}

GET/api/v1/docs/:id

Get document

Retrieves a single document including its plain-text content. You must be a member of the document's workspace.

Path parameters

Parameter	Type	Description
idrequired	string	The document ID (CUID).

Example request

bash

curl https://notesmith.io/api/v1/docs/cma1b2c3d4e5f6g7h8i9j0 \
  -H "Authorization: Bearer ns_your_key_here"

Response

json

{
  "id":          "cma1b2c3d4e5f6g7h8i9j0",
  "title":       "Q3 Planning Notes",
  "icon":        "📋",
  "workspaceId": "cma0z9y8x7w6v5u4t3s2r1",
  "folderId":    null,
  "content":     "Q3 Planning Notes\n\nOwner: Jane Smith\n...",
  "createdAt":   "2025-06-01T10:00:00.000Z",
  "updatedAt":   "2025-06-15T14:32:00.000Z",
  "createdBy": {
    "id":    "usr_abc123",
    "name":  "Jane Smith",
    "email": "[email protected]"
  }
}

PATCH/api/v1/docs/:id

Update document

Updates a document's title and/or content. You must have at least Member role in the workspace. Only the fields you include are changed — this is a partial update.

Path parameters

Parameter	Type	Description
idrequired	string	The document ID to update.

Request body

Field	Type	Description
title	string	New title for the document. Max 500 characters.
content	string	New document body as plain Markdown. Replaces the existing content.
icon	string	New emoji icon. Pass an empty string to remove the icon.
folderId	string \| null	Move the document to this folder, or pass `null` to move it to the workspace root.

Example request

bash

curl -X PATCH https://notesmith.io/api/v1/docs/cma1b2c3d4e5f6g7h8i9j0 \
  -H "Authorization: Bearer ns_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title":   "Q3 Planning Notes (Updated)",
    "content": "# Q3 Planning\n\nUpdated via API."
  }'

Response

json

{
  "id":        "cma1b2c3d4e5f6g7h8i9j0",
  "title":     "Q3 Planning Notes (Updated)",
  "icon":      "📋",
  "folderId":  null,
  "updatedAt": "2025-06-15T15:10:00.000Z"
}

Workspaces

List the workspaces your API key has access to.

GET/api/v1/workspaces

List workspaces

Returns all workspaces the authenticated user belongs to, along with their role in each. Use workspace IDs when creating documents or listing docs.

Example request

bash

curl https://notesmith.io/api/v1/workspaces \
  -H "Authorization: Bearer ns_your_key_here"

Response

json

[
  {
    "id":        "cma0z9y8x7w6v5u4t3s2r1",
    "name":      "Acme Corp",
    "slug":      "acme-corp",
    "icon":      "🏢",
    "plan":      "PRO",
    "role":      "OWNER"
  },
  {
    "id":        "cmb1a2b3c4d5e6f7g8h9i0",
    "name":      "Personal",
    "slug":      "personal",
    "icon":      null,
    "plan":      "FREE",
    "role":      "MEMBER"
  }
]

Users

Retrieve information about the authenticated user.

GET/api/v1/me

Get current user

Returns the profile of the user whose API key is used in the request. Useful for verifying your key is valid and retrieving your user ID.

Example request

bash

curl https://notesmith.io/api/v1/me \
  -H "Authorization: Bearer ns_your_key_here"

Response

json

{
  "id":    "usr_abc123",
  "name":  "Jane Smith",
  "email": "[email protected]",
  "image": "https://example.com/avatar.png"
}

Notes & limits

Content format. The content field accepts plain Markdown on write and returns plain text on read. Rich formatting (headings, lists, code blocks, etc.) is preserved when edited inside the NoteSmith editor.

API keys. Each account can have up to 10 API keys. Keys are hashed on storage — the raw key is only shown once at creation time. Revoke keys from Settings → API Keys.

Workspace membership. Your API key inherits your workspace permissions. Viewer-role members cannot create or update documents.

Deleted documents. Soft-deleted documents are not returned by any endpoint. Requests targeting a deleted document return 404 Not Found.

Need help?

Reach us at [email protected]

Create an API key View features