Skip to main content

​
Overview

Personal knowledge management — structured and unstructured notes with bidirectional linking. Inspired by Obsidian, Bear, and Apple Notes, but API-first. Store Markdown content, organize in notebooks, link notes to each other and to entities in other domains (contacts, tasks, events, deals). Notes are the connective layer for your knowledge graph. A note about a meeting links to the event, the attendees’ contact cards, and the follow-up tasks.

​
Data Model

​
Entities

EntityDescription
NotebookAn organizational container for notes (like a folder)
NoteA document with title, Markdown body, and metadata
Note LinkA directional link from a note to another entity
Note TagA label attached to a note for categorization
Note Tag DefinitionA tenant-scoped tag type (name + optional color)
Note AttachmentA URL reference to an external file attached to a note

​
Relationships

  • A Note optionally belongs to a Notebook
  • A Note can have many Links, Tags, and Attachments
  • Links point from a note to any entity type (note, contact, task, event, deal)

​
Key Concepts

​
Notebooks

Notebooks are optional organizational containers. Notes can exist without a notebook. Each notebook tracks a note count for display purposes.

​
Markdown body

Note content is stored as Markdown in the body field. The API stores raw Markdown — rendering is the client’s responsibility.

​
Frontmatter as metadata

YAML frontmatter is parsed and stored in the note’s metadata JSONB field. This enables structured data (tags, custom fields, dates) alongside free-form content. Notes support [[wikilink]] syntax for linking between notes. The system maintains bidirectional link awareness:
  • Outgoing links (GET /api/v1/notes/{id}/links) — what this note links to
  • Backlinks (GET /api/v1/notes/{id}/backlinks) — what notes link to this note
This creates a navigable knowledge graph. Note links aren’t limited to other notes. Link a note to any entity type:
Entity TypeExample use case
noteWiki-style links between notes
contactMeeting notes linked to attendees
taskNotes linked to tasks they describe
eventNotes linked to calendar events
dealNotes linked to CRM deals
Use GET /api/v1/backlinks/{entity_type}/{entity_id} to find all notes that link to any entity across all domains.

​
Tags

Tags are lightweight labels for categorizing notes. Tag definitions are tenant-scoped (created once, applied to many notes). Each tag has a name and optional color.

​
Attachments

Attachments are URL references to external files (images, documents, etc.). The API stores the URL and metadata — it does not host files.

​
Pinning and archiving

Notes have is_pinned and is_archived boolean fields. Pinned notes appear at the top of lists. Archived notes are hidden from default list results but can be filtered for.

​
Full-text search

Search across note titles and body content using the q parameter on GET /api/v1/notes.

​
MCP Tools

ToolDescription
notes_searchFree-text search across all notes
notes_getGet a note’s full content plus backlinks
notes_createCreate a new note with optional notebook, tags, and links
notes_updateModify note content, title, tags, or notebook
notes_deleteRemove a note
notes_list_backlinksSee everything that links to a given note
See the MCP guide for setup instructions.

​
API Endpoints

See the API Reference for the full endpoint list with request/response details.

​
Examples

​
Create a notebook and a note

# Create a notebook
curl -X POST https://api.backside.app/api/v1/notebooks \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Meeting Notes"}'

# Create a note in the notebook
curl -X POST https://api.backside.app/api/v1/notes \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q2 Planning Meeting",
    "body": "## Decisions\n\n- Launch API by April 15\n- Hire two more engineers\n\n## Action Items\n\nSee linked tasks.",
    "notebook_id": "uuid-of-notebook"
  }'

# Link to a contact
curl -X POST https://api.backside.app/api/v1/notes/{id}/links \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "target_entity_type": "contact",
    "target_entity_id": "uuid-of-contact"
  }'

# Link to a task
curl -X POST https://api.backside.app/api/v1/notes/{id}/links \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "target_entity_type": "task",
    "target_entity_id": "uuid-of-task"
  }'

​
Find all notes linked to a contact

curl https://api.backside.app/api/v1/backlinks/contact/{contact_id} \
  -H "Authorization: Bearer bsk_live_..."