Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Manage Notes
description: Create, list, search, update, and delete notes

---


# Manage Notes

CRUD endpoints for organization-wide notes. Scoped agents see only notes they have been granted access to; human callers (Clerk JWT) and admin API keys see every note in the org.

---

## Create note `POST`


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** (JWT or admin key): no access row is inserted. The note stays invisible to all scoped agents until an admin grants them.

### 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**

```bash
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."}'
```

**JavaScript**

```javascript
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();
```

**Python**

```python
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`


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**

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

**JavaScript**

```javascript
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();
```

**Python**

```python
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`


Fetch a single note by ID.

### Path parameters

| Parameter | Type | Description |
| :--- | :--- | :--- |
| `note_id` | UUID | Note ID |

### Code examples

**cURL**

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

**JavaScript**

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

**Python**

```python
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`


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**

```bash
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)"}'
```

**JavaScript**

```javascript
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();
```

**Python**

```python
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`


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

### Code examples

**cURL**

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

**JavaScript**

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

**Python**

```python
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` or `deleted` |
| `created_at` | string | ISO 8601 |
| `updated_at` | string | ISO 8601 |
| `access` | object[] | Inlined [access rules](/docs/api/notes/access#access-rule-object). Empty for human-created notes until granted; single-element for agent creators; more entries after admin grants. |