Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ivory.finance/llms.txt

Use this file to discover all available pages before exploring further.

​
What is the Intelligence Editor?

The Ivory Intelligence Editor is a block-based document system built on top of Tiptap + Yjs. It gives your users a collaborative workspace where documents contain smart blocks — live financial data (SEC filings, market metrics, charts, AI insights) embedded directly alongside regular prose.

Document CRUD

Create, read, update, soft-delete documents and workspaces. Control visibility and share with team members.

Real-Time Collaboration

Hocuspocus WebSocket server backed by Yjs CRDT. Multiple cursors, live edits, offline sync.

Smart Blocks

Five resolver endpoints that return fully-formed Tiptap block nodes populated with live financial data.

Orchestrator Tools

The AI orchestrator can read, search, and write into documents via read_editor_document, search_editor_documents, write_to_editor_document, and three smart block creation tools.

​
Data model

​
Hierarchy

Workspace  (optional grouping)
└── Document
    ├── doc_ast       (Tiptap JSON — authoritative content for agents + REST)
    ├── yjs_state     (Yjs CRDT binary — authoritative for real-time collab)
    └── document_versions[]  (snapshots)
A document can exist outside any workspace (workspace_id = null) or be placed inside one.

​
Document fields

FieldTypeDescription
iduuidDocument UUID — used as the Hocuspocus room name
tenant_idstringOwner’s user_id
workspace_iduuid | nullParent workspace (optional)
titlestringDocument title
iconstring | nullEmoji or icon identifier
cover_urlstring | nullCover image URL
visibilityprivate | workspace | publicAccess scope
doc_astobjectTiptap/ProseMirror JSON — read and written by agents and REST
yjs_statebytesBinary Yjs CRDT state — managed by Hocuspocus only
word_countintegerAuto-updated on doc_ast writes
updated_by_typeuser | agent | systemWho made the last change
updated_by_idstringUser ID or agent name
is_deletedbooleanSoft-delete flag

​
Access model

A user can see a document if any one of these is true: 
1. They are the document creator (documents.created_by == user_id)
2. They are an explicit document_member
3. The document visibility == 'workspace' AND they are a workspace_member
4. The document visibility == 'public'   (read-only viewer)

​
Roles

Documents use a ranked role system:
RoleRankCan readCan editCan shareCan delete
owner4✓✓✓✓
editor3✓✓✗✗
commenter2✓✗✗✗
viewer1✓✗✗✗
Public documents are always viewer for non-owners. Workspace members inherit editor (for admins/editors) or viewer.

​
Visibility and OpenSearch indexing

Every document is indexed for semantic search. The indexing topology is visibility-aware:
VisibilityTenant index (ivory_editor_docs_{tenant_id})Public index (ivory_editor_docs_public)
private✓✗
workspace✓✗
public✓✓
This means:
  • Private/workspace documents are only searchable by their owner via scope='private'
  • Public documents are discoverable by anyone via scope='public'
  • Setting a document to public automatically adds it to the global search index
  • Changing back to private automatically removes it from the public index
The AI orchestrator search_editor_documents tool exposes scope: private | public | all.

​
Tiptap doc_ast format

All document content is stored as a Tiptap/ProseMirror JSON tree: 
{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 1 },
      "content": [{ "type": "text", "text": "Apple FY2025 Analysis" }]
    },
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "Revenue grew 12% YoY in Q4 2025." }]
    },
    {
      "type": "sec_citation",
      "attrs": {
        "block_id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "loaded",
        "accession_number": "0000320193-25-000001",
        "company_name": "APPLE INC",
        "form_type": "10-K",
        "excerpts": [{ "text": "Net sales increased 12% ...", "heading": "Results of Operations", "score": 0.94 }]
      }
    }
  ]
}
Smart block nodes have a type matching one of the five block types (sec_citation, market_data, ai_insight, sql_query, ivory_chart) with a rich attrs object. See Smart Blocks for the full schema.

​
Agent write traceability

When the AI orchestrator writes to a document, every change is tagged: 
{
  "updated_by_type": "agent",
  "updated_by_id": "orchestrator"
}
This gives users a full audit trail in GET /v1/editor/documents/{doc_id}. The orchestrator respects ownership — it can only write to documents owned by the requesting tenant.

​
Authentication

All editor endpoints require a standard JWT Bearer token (same as the rest of the Ivory API): 
Authorization: Bearer <jwt>
The only exceptions are:
  • GET /v1/editor/documents/{doc_id} on a public document — viewer access is granted without auth
  • POST /v1/editor/hocuspocus/auth — takes the JWT in the request body (called by the WebSocket server, not the browser)
  • PUT /v1/editor/documents/{doc_id}/yjs — authenticated via X-Hocuspocus-Secret header (internal)