Manage Notes

CRUD endpoints for organization-wide notes. Scoped agents see only notes they have been granted access to; users in the Inkbox Console and admin-scoped API keys see every note in the org.

Create note

POST /notes

Create a new note. created_by is stamped server-side from the auth context — any client-supplied value is rejected.

Agent creator (scoped API key): a per-identity access row is auto-inserted, making the note immediately visible to that agent. Other agents cannot see it until granted.
Human creator (Console user or admin-scoped API key): no access row is inserted. The note stays invisible to all scoped agents until access is granted.

Request body

Field	Type	Required	Description
`title`	string \| null	No	Short title (max 255 chars)
`body`	string	Yes	Note body (1–100000 chars, stored byte-for-byte)

Request example

JSON

{
  "title": "Sprint planning",
  "body": "Discussed Q2 roadmap. Focus: agent-signup flow, contact access UX."
}

Response (201)

JSON

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "org_123",
  "created_by": "user_2abc123",
  "title": "Sprint planning",
  "body": "Discussed Q2 roadmap. Focus: agent-signup flow, contact access UX.",
  "status": "active",
  "created_at": "2026-04-21T12:30:00Z",
  "updated_at": "2026-04-21T12:30:00Z",
  "access": [
    {
      "id": "r1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "note_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "created_at": "2026-04-21T12:30:00Z"
    }
  ]
}

Error responses

Status	Description
422	Body too long, or client sent `created_by` (rejected by `extra: forbid`)

Code examples

curl -X POST "https://inkbox.ai/api/v1/notes" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Sprint planning", "body": "Discussed Q2 roadmap."}'

const response = await fetch("https://inkbox.ai/api/v1/notes", {
  method: "POST",
  headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
  },
  body: JSON.stringify({
      title: "Sprint planning",
      body: "Discussed Q2 roadmap.",
  }),
});
const note = await response.json();

import requests

response = requests.post(
    "https://inkbox.ai/api/v1/notes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"title": "Sprint planning", "body": "Discussed Q2 roadmap."},
)
note = response.json()

List notes

GET /notes

List notes visible to the caller.

Query parameters

Parameter	Type	Default	Description
`q`	string	—	Full-text search over title + body, max 200 chars
`identity_id`	UUID	—	Filter to notes granted to this identity
`limit`	integer	50	1–200
`offset`	integer	0	Offset for pagination
`order`	string	`recent`	`"recent"` (updated_at desc) or `"created"` (created_at desc)

Response (200)

Returns an array of note objects with inlined access arrays.

Code examples

curl -X GET "https://inkbox.ai/api/v1/notes?q=roadmap&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  "https://inkbox.ai/api/v1/notes?q=roadmap&limit=20",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const notes = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/notes",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"q": "roadmap", "limit": 20},
)
notes = response.json()

Get note

GET /notes/{note_id}

Fetch a single note by ID.

Path parameters

Parameter	Type	Description
`note_id`	UUID	Note ID

Code examples

curl -X GET "https://inkbox.ai/api/v1/notes/NOTE_ID" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/notes/${noteId}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const note = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/notes/{note_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
note = response.json()

Update note

PATCH /notes/{note_id}

Update a note. Any caller who can see the note can patch it.

Path parameters

Parameter	Type	Description
`note_id`	UUID	Note ID

Request body

Field	Type	Required	Description
`title`	string \| null	No	Omit to leave unchanged, send `null` to clear, or send a string to set
`body`	string	No	Omit to leave unchanged, or send a new body. Sending `null` is not a legal operation (body is required) — returns 422.

created_by, organization_id, status, and timestamps are immutable.

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/notes/NOTE_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Sprint planning (revised)"}'

const response = await fetch(
  `https://inkbox.ai/api/v1/notes/${noteId}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ title: "Sprint planning (revised)" }),
  }
);
const note = await response.json();

import requests

response = requests.patch(
    f"https://inkbox.ai/api/v1/notes/{note_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"title": "Sprint planning (revised)"},
)
note = response.json()

Delete note

DELETE /notes/{note_id}

Delete a note. Returns 204 No Content on success. Any caller who can see the note can delete it.

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/notes/NOTE_ID" \
  -H "X-API-Key: YOUR_API_KEY"

await fetch(
  `https://inkbox.ai/api/v1/notes/${noteId}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

requests.delete(
    f"https://inkbox.ai/api/v1/notes/{note_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

Note object

Field	Type	Description
`id`	UUID	Unique note identifier
`organization_id`	string	Owning organization
`created_by`	string	Opaque creator stamp (user ID or identity ID). Immutable, server-populated.
`title`	string \| null	Optional short title
`body`	string	Note body (required, 1–100000 chars)
`status`	string	`active`
`created_at`	string	ISO 8601
`updated_at`	string	ISO 8601
`access`	object[]	Inlined access rules. Empty for human-created notes until granted; single-element for agent creators; more entries after admin grants.

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

Create note

Request body

Request example

Response (201)

Error responses

Code examples

List notes

Query parameters

Response (200)

Code examples

Get note

Path parameters

Code examples

Update note

Path parameters

Request body

Code examples

Delete note

Code examples

Note object

​Create note

​Request body

​Request example

​Response (201)

​Error responses

​Code examples

​List notes

​Query parameters

​Response (200)

​Code examples

​Get note

​Path parameters

​Code examples

​Update note

​Path parameters

​Request body

​Code examples

​Delete note

​Code examples

​Note object

Create note

Request body

Request example

Response (201)

Error responses

Code examples

List notes

Query parameters

Response (200)

Code examples

Get note

Path parameters

Code examples

Update note

Path parameters

Request body

Code examples

Delete note

Code examples

Note object