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}`,
);