roam-sdk 0.4.0

Roam Research SDK and terminal UI client
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# Getting Started

## Add the dependency

```bash
cargo add roam-sdk
```

Or add to `Cargo.toml`:

```toml
[dependencies]
roam-sdk = "0.3"
tokio = { version = "1", features = ["full"] }
```

## Create a client

```rust
use roam_sdk::RoamClient;

let client = RoamClient::new("your-graph-name", "your-api-token");
```

The graph name is the one that appears in your Roam URL. The API token can be generated in Roam under **Settings > Graph > API tokens**.

## Read a daily note

```rust
use roam_sdk::{RoamClient, queries, types::DailyNote};
use chrono::NaiveDate;

#[tokio::main]
async fn main() -> roam_sdk::Result<()> {
    let client = RoamClient::new("my-graph", "my-token");

    let date = NaiveDate::from_ymd_opt(2026, 2, 21).unwrap();
    let uid = queries::daily_note_uid_for_date(2, 21, 2026); // "02-21-2026"
    let (eid, selector) = queries::pull_daily_note(&uid);

    let resp = client.pull(eid, &selector).await?;
    let note = DailyNote::from_pull_response(date, uid, &resp.result);

    println!("Title: {}", note.title);
    for block in &note.blocks {
        println!("  - {}", block.string);
    }

    Ok(())
}
```

## Read any page

```rust
let (eid, selector) = queries::pull_page_by_title("My Page");
let resp = client.pull(eid, &selector).await?;
let note = DailyNote::from_pull_response(
    NaiveDate::from_ymd_opt(2000, 1, 1).unwrap(), // dummy date for non-daily pages
    resp.result.get(":block/uid")
        .and_then(|v| v.as_str())
        .unwrap_or("")
        .to_string(),
    &resp.result,
);
```

## Find linked references

```rust
use roam_sdk::{queries, types};

let query = queries::linked_refs_query("Projects");
let resp = client.query(query, vec![]).await?;
let groups = types::parse_linked_refs(&resp.result, "Projects");

for group in &groups {
    println!("From page: {}", group.page_title);
    for block in &group.blocks {
        println!("  - {}", block.string);
    }
}
```

## Write operations

```rust
use roam_sdk::types::*;

// Create a block
client.write(WriteAction::CreateBlock {
    location: BlockLocation {
        parent_uid: "page-uid".into(),
        order: OrderValue::Position("last".into()),
    },
    block: NewBlock {
        string: "Hello from Rust!".into(),
        uid: None,
        open: None,
    },
}).await?;

// Update a block
client.write(WriteAction::UpdateBlock {
    block: BlockUpdate {
        uid: "block-uid".into(),
        string: "Updated text".into(),
    },
}).await?;

// Delete a block
client.write(WriteAction::DeleteBlock {
    block: BlockRef { uid: "block-uid".into() },
}).await?;

// Move a block
client.write(WriteAction::MoveBlock {
    block: BlockRef { uid: "block-uid".into() },
    location: BlockLocation {
        parent_uid: "new-parent-uid".into(),
        order: OrderValue::Index(0),
    },
}).await?;
```

## Error handling

```rust
use roam_sdk::RoamError;

match client.pull(eid, &selector).await {
    Ok(resp) => println!("{}", resp.result),
    Err(RoamError::Api { status: 429, .. }) => {
        eprintln!("Rate limited — wait and retry");
    }
    Err(RoamError::Api { status: 401, .. }) => {
        eprintln!("Invalid token — check your credentials");
    }
    Err(e) => eprintln!("Error: {}", e),
}
```