This document will guide you through all available backend API calls, which can be invoked using orca.invokeBackend.
Changes a single/multi choice property value across all blocks that use it.
Parameters:
Returns:
An array of updated blocks that had the choice value changed.
Example:
// Change a choice value from "In Progress" to "In Development"
// for all blocks using this tag property
const updatedBlocks = await orca.invokeBackend(
"change-tag-property-choice",
tagBlockId,
"status",
"In Progress",
"In Development",
)
// Update frontend state with the modified blocks
for (const block of updatedBlocks) {
orca.state.blocks[block.id] = block
}
Exports the specified block as a PNG image file.
Parameters:
Returns:
On success returns a tuple [true, string] where the second element is the exported file path; on failure returns [false, Error] or an Error-like value.
Example:
// Request backend to export a block as PNG with a width of 1200px
const [ok, result] = await orca.invokeBackend(
"export-png",
"my-repo",
12345,
1200,
)
if (ok) {
console.log("Exported PNG:", result) // result = path to saved PNG
} else {
console.error("Export failed:", result)
}
Retrieves all blocks with the specified alias.
Parameters:
Returns:
A list of blocks with aliases.
Example:
// Get aliased blocks matching a keyword, with pagination
const blocks = await orca.invokeBackend("get-aliased-blocks", "project", 0, 10)
Retrieves all aliases in the repository.
Parameters:
Returns:
A list of aliases.
Example:
// Get aliases matching a keyword, with pagination
const aliases = await orca.invokeBackend("get-aliases", "meeting", 0, 20)
Retrieves block IDs for a list of aliases.
Parameters:
Returns:
A mapping of aliases to block IDs.
Example:
// Get block IDs for a list of aliases
const blockIds = await orca.invokeBackend("get-aliases-ids", [
"project-a",
"task-1",
])
Retrieves a block by its ID.
Parameters:
Returns:
The block object.
Example:
// Get a block by its ID
const block = await orca.invokeBackend("get-block", 12345)
console.log(`Block content: ${block.text}`)
Retrieves a block by its alias.
Parameters:
Returns:
The block object.
Example:
// Get a block using its alias
const block = await orca.invokeBackend("get-block-by-alias", "project-roadmap")
Retrieves the ID of a block by its alias.
Parameters:
Returns:
An object containing the block ID.
Example:
// Get the ID of a block by its alias
const result = await orca.invokeBackend("get-blockid-by-alias", "meeting-notes")
if (result?.id != null) {
console.log(`Found block ID: ${result.id}`)
}
Retrieves multiple blocks by their IDs.
Parameters:
Returns:
An array of block objects.
Example:
// Get multiple blocks by their IDs
const blocks = await orca.invokeBackend("get-blocks", [123, 456, 789])
Retrieves blocks with specific tags.
Parameters:
Returns:
An array of blocks containing the specified tags.
Example:
// Get blocks with specific tags
const taggedBlocks = await orca.invokeBackend("get-blocks-with-tags", [
"project",
"active",
])
console.log(`Found ${taggedBlocks.length} active projects`)
Retrieves a block and all its nested child blocks (tree structure).
Parameters:
Returns:
The block tree structure.
Example:
// Get a block and all its nested children
const blockTree = await orca.invokeBackend("get-block-tree", 12345)
Retrieves child tags of a parent tag block.
Parameters:
Returns:
An array of child tags.
Example:
// Get child tags of a parent tag block
const childTags = await orca.invokeBackend(
"get-children-tags",
parentTagBlockId,
)
Retrieves the journal block for a specific date.
Parameters:
Returns:
The journal block.
Example:
// Get the journal block for today's date
const journalBlock = await orca.invokeBackend("get-journal-block", new Date())
Retrieves all remindings for a specific date range.
Parameters:
Returns:
An array of remindings within the specified date range.
Example:
// Get remindings for a date range
const startDate = new Date(2025, 0, 1)
const endDate = new Date(2025, 11, 31)
const remindings = await orca.invokeBackend(
"get-remindings",
startDate,
endDate,
)
Performs Optical Character Recognition (OCR) on an image file.
Parameters:
Returns:
The OCR results containing recognized text and positions.
Example:
// OCR from a file path
const ocrResult = await orca.invokeBackend("image-ocr", "./assets/document.png")
// OCR from binary data
const response = await fetch("https://example.com/image.jpg")
const imageData = await response.arrayBuffer()
const ocrResult = await orca.invokeBackend("image-ocr", imageData)
console.log(`OCR text recognized: ${ocrResult.length} elements`)
Executes a complex query to search and filter blocks.
Parameters:
Returns:
An array of blocks matching the query.
Example:
// Search for blocks with a complex query
const results = await orca.invokeBackend("query", {
q: {
kind: 1, // AND
conditions: [
{ kind: 3, start: { t: 1, v: 7, u: "d" }, end: { t: 1, v: 0, u: "d" } }, // Journal entries from last week
{ kind: 8, text: "meeting" }, // Containing the word "meeting"
],
},
sort: [["modified", "DESC"]],
pageSize: 20,
})
Searches for aliases containing specific text.
Parameters:
Returns:
An array of matching aliases.
Example:
// Search for aliases containing a keyword
const matchingAliases = await orca.invokeBackend("search-aliases", "project")
Searches for blocks containing specific text.
Parameters:
Returns:
An array of matching blocks.
Example:
// Search for blocks containing specific text
const blocks = await orca.invokeBackend(
"search-blocks-by-text",
"meeting agenda",
)
Sets an application-level configuration option.
Parameters:
Returns:
void
Example:
// Set an application-level configuration option
await orca.invokeBackend("set-app-config", AppKeys.AIModel, "gpt-4")
orca.broadcasts.broadcast(BroadcastMsgs.RefreshSettings, AppKeys.AIModel)
Sets a repository-level configuration option.
Parameters:
Returns:
void
Example:
// Set a repository-level configuration option
await orca.invokeBackend("set-config", RepoKeys.DefaultBlockType, "text")
Opens a URL or file using the system's default application.
Parameters:
Returns:
The result of the open operation.
Example:
// Open a URL in the default browser
await orca.invokeBackend("shell-open", "https://example.com")
// Open a local file with its associated application
await orca.invokeBackend("shell-open", "/path/to/document.pdf")
Displays a file in the system's file explorer (e.g., Finder on macOS, Explorer on Windows).
Parameters:
Returns:
void
Example:
// Show a file in the system's file explorer
await orca.invokeBackend("show-in-folder", "/path/to/file.txt")
Uploads a binary asset (e.g., an image) to the repository.
Parameters:
Returns:
The relative path of the uploaded asset.
Example:
// Upload an image as a binary asset
const imageData = new Uint8Array([...]) // Binary image data
const assetPath = await orca.invokeBackend("upload-asset-binary", "image/png", imageData.buffer)
if (assetPath) {
console.log(`Image uploaded to: ${assetPath}`)
}
Uploads multiple asset files to the repository.
Parameters:
Returns:
The upload result, including successfully uploaded and failed files.
Example:
// Upload multiple files to the repository
const result = await orca.invokeBackend("upload-assets", [
"/path/to/image1.jpg",
"/path/to/image2.png",
])
console.log(
`Uploaded: ${result.uploaded.length}, Failed: ${result.failed.length}`,
)