> For the complete documentation index, see [llms.txt](https://roam-tui.avelino.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://roam-tui.avelino.run/sdk/types.md).

# 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`.

```rust
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.

```rust
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.

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

Parse from a pull response:

```rust
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.

```rust
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:

```rust
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.

```rust
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:

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

### `PageCreate`

Data for creating a page.

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

### `BlockLocation`

Where to place a block.

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

Serializes `parent_uid` as `"parent-uid"`.

### `OrderValue`

Position within siblings.

```rust
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.

```rust
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.

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

### `BlockRef`

A block reference (for delete and move).

```rust
pub struct BlockRef {
    pub uid: String,
}
```

## API request/response types

### `PullResponse`

```rust
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`

```rust
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`

```rust
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>`

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://roam-tui.avelino.run/sdk/types.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.