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.

---

# Notes
description: Record and search shared notes across your agents using the Inkbox SDK and CLI

---


# Notes

Notes are free-form org-scoped text — a `title` and a `body` — that your agents (and humans) can save, search, and share. Use them for anything that needs to outlive a single conversation: meeting summaries, research snippets, reminders to other agents, customer context that a future turn should see.

**Visibility rules.** Human users see every note in the org. Agents see notes only when granted. An agent that creates a note is auto-granted to that note; peers need an explicit grant from an admin or human user.

## Creating a note

`body` is required and can be up to 100 000 characters. `title` is optional but handy for search results and UI lists.

**Python**

```python
note = inkbox.notes.create(
    title="Customer onboarding call — Acme",
    body=(
        "Jane Doe walked through requirements. Pain points: data export, "
        "SSO for their vendor portal. Next step: schedule demo for 2026-05-03."
    ),
)
print(note.id, note.created_by)
```

**TypeScript**

```typescript
const note = await inkbox.notes.create({
    title: "Customer onboarding call — Acme",
    body:
        "Jane Doe walked through requirements. Pain points: data export, " +
        "SSO for their vendor portal. Next step: schedule demo for 2026-05-03.",
});
console.log(note.id, note.createdBy);
```

**CLI**

```bash
inkbox notes create \\
  --title "Customer onboarding call — Acme" \\
  --body "Jane Doe walked through requirements..."
```

## Full-text search

`notes.list` accepts a `q` parameter that runs a full-text search over `title + body`. Combine it with `identity_id` to filter to notes visible to a specific agent, or `order` to sort by most-recent activity vs creation time.

**Python**

```python
# Recent notes first
notes = inkbox.notes.list(limit=20)

# Full-text search
hits = inkbox.notes.list(q="onboarding")
for n in hits:
    print(n.title, "-", n.created_at)

# Notes granted to a specific agent
sales_notes = inkbox.notes.list(identity_id=sales_agent.id)

# Oldest created first
oldest = inkbox.notes.list(order="created", limit=20)
```

**TypeScript**

```typescript
// Recent notes first
const notes = await inkbox.notes.list({ limit: 20 });

// Full-text search
const hits = await inkbox.notes.list({ q: "onboarding" });
for (const n of hits) {
    console.log(n.title, "-", n.createdAt);
}

// Notes granted to a specific agent
const salesNotes = await inkbox.notes.list({ identityId: salesAgent.id });

// Oldest created first
const oldest = await inkbox.notes.list({ order: "created", limit: 20 });
```

**CLI**

```bash
# Recent notes
inkbox notes list --limit 20

# Full-text search
inkbox notes list --q onboarding

# Filter to notes an agent can see
inkbox notes list --identity <identity-id>
```

## Updating and deleting

Updates use JSON-merge-patch: omit a field to leave it unchanged, send `null` on `title` to clear it. `body` cannot be cleared — send a new string to replace it, or delete the whole note.

**Python**

```python
# Replace just the title
note = inkbox.notes.update(note.id, title="Customer onboarding — Acme (follow-up sent)")

# Clear the title
note = inkbox.notes.update(note.id, title=None)

# Replace the body
note = inkbox.notes.update(note.id, body="Updated minutes from the 2026-05-03 demo.")

# Delete the note
inkbox.notes.delete(note.id)
```

**TypeScript**

```typescript
// Replace just the title
let n = await inkbox.notes.update(note.id, {
    title: "Customer onboarding — Acme (follow-up sent)",
});

// Clear the title
n = await inkbox.notes.update(note.id, { title: null });

// Replace the body
n = await inkbox.notes.update(note.id, {
    body: "Updated minutes from the 2026-05-03 demo.",
});

// Delete the note
await inkbox.notes.delete(note.id);
```

**CLI**

```bash
# Update title
inkbox notes update <note-id> --title "Customer onboarding — Acme"

# Replace body
inkbox notes update <note-id> --body "Updated minutes..."

# Delete
inkbox notes delete <note-id>
```

## Controlling visibility

Agents that create a note are auto-granted to it. Sharing to other agents is an admin (or JWT human) operation.

**Python**

```python
# Share a note with another agent (admin or JWT call)
inkbox.notes.access.grant(note.id, identity_id=support_agent.id)

# List who has access
rules = inkbox.notes.access.list(note.id)
for r in rules:
    print(r.identity_id, r.created_at)

# Revoke access
inkbox.notes.access.revoke(note.id, identity_id=support_agent.id)
```

**TypeScript**

```typescript
// Share a note with another agent (admin or JWT call)
await inkbox.notes.access.grant(note.id, supportAgent.id);

// List who has access
const rules = await inkbox.notes.access.list(note.id);
for (const r of rules) {
    console.log(r.identityId, r.createdAt);
}

// Revoke access
await inkbox.notes.access.revoke(note.id, supportAgent.id);
```

**CLI**

```bash
# Share a note (admin operation)
inkbox notes access grant <note-id> <identity-id>

# List who has access
inkbox notes access list <note-id>

# Revoke
inkbox notes access revoke <note-id> <identity-id>
```

## Related

- [Notes API reference](/docs/api/notes)
- [Access control reference](/docs/api/notes/access)