Types

All types are in roam_sdk::types (re-exported from roam_sdk::api::types).

Data structures

Block

A block in the Roam graph. Blocks form a tree via children.

pub struct Block {
    pub uid: String,
    pub string: String,
    pub order: i64,
    pub children: Vec<Block>,
    pub open: bool,
    pub refs: Vec<RefEntity>,
}

• uid — unique block identifier

• string — the block's text content (Roam markdown)

• order — sort position among siblings

• children — nested child blocks (recursive tree)

• open — whether children are expanded or collapsed

• refs — page/block references contained in this block (not serialized to JSON)

RefEntity

A reference target found in a block.

pub struct RefEntity {
    pub uid: String,
    pub title: Option<String>,   // page title, if it's a page ref
    pub string: Option<String>,  // block text, if it's a block ref
}

DailyNote

A daily note page with its blocks.

pub struct DailyNote {
    pub date: chrono::NaiveDate,
    pub uid: String,
    pub title: String,
    pub blocks: Vec<Block>,
}

Parse from a pull response:

let note = DailyNote::from_pull_response(date, uid, &pull_response.result);

Blocks are automatically sorted by order. Nested children are parsed recursively.

LinkedRefBlock / LinkedRefGroup

Results from a linked references query, grouped by source page.

pub struct LinkedRefBlock {
    pub uid: String,
    pub string: String,
    pub page_title: String,
}

pub struct LinkedRefGroup {
    pub page_title: String,
    pub blocks: Vec<LinkedRefBlock>,
}

Parse from a query response:

let groups = parse_linked_refs(&query_response.result, "Current Page");

Self-references (blocks from the current page) are automatically filtered out. Groups are sorted alphabetically by page title, blocks within each group sorted by text.

Write actions

WriteAction

An enum representing mutations to the graph.

pub enum WriteAction {
    CreateBlock { location: BlockLocation, block: NewBlock },
    UpdateBlock { block: BlockUpdate },
    DeleteBlock { block: BlockRef },
    MoveBlock { block: BlockRef, location: BlockLocation },
    CreatePage { page: PageCreate },
    BatchActions { actions: Vec<WriteAction> },
}

Serializes with a "action" tag: "create-block", "update-block", "delete-block", "move-block", "create-page", "batch-actions".

WriteAction implements both Serialize and Deserialize, so you can parse action JSON:

let actions: Vec<WriteAction> = serde_json::from_str(json_string)?;

PageCreate

Data for creating a page.

pub struct PageCreate {
    pub title: String,
    pub uid: Option<String>,
}

BlockLocation

Where to place a block.

pub struct BlockLocation {
    pub parent_uid: String,
    pub order: OrderValue,
}

Serializes parent_uid as "parent-uid".

OrderValue

Position within siblings.

pub enum OrderValue {
    Index(i64),           // specific position (0-based)
    Position(String),     // "last", "first"
}

Serializes as either a number (0) or a string ("last").

NewBlock

Data for creating a block.

pub struct NewBlock {
    pub string: String,
    pub uid: Option<String>,
    pub open: Option<bool>,
}

uid and open are omitted from JSON when None.

BlockUpdate

Data for updating a block's text.

pub struct BlockUpdate {
    pub uid: String,
    pub string: String,
}

BlockRef

A block reference (for delete and move).

pub struct BlockRef {
    pub uid: String,
}

API request/response types

PullResponse

pub struct PullResponse {
    pub result: serde_json::Value,
}

The result is a raw JSON value matching the pull selector shape. Use .get(":attribute") to access fields.

QueryResponse

pub struct QueryResponse {
    pub result: Vec<Vec<serde_json::Value>>,
}

Each inner Vec is a result row. Values correspond to :find variables in order.

Error types

RoamError

pub enum RoamError {
    Api { status: u16, message: String },
    Http(reqwest::Error),
    Config(String),
    Io(std::io::Error),
    Json(serde_json::Error),
    TomlDe(toml::de::Error),
}

Implements std::error::Error and Display. Conversions from reqwest::Error, std::io::Error, serde_json::Error, and toml::de::Error via From.

Result<T>

pub type Result<T> = std::result::Result<T, RoamError>;