Searching and retrieving

References first, bodies second

A search returns small references and their facts; bodies arrive with a download. The download names the SHA-256 of the exact bytes, and the service checks the body against it before it reaches your harness.

1Searchintelligence_searchDescribe what the step needs and read the references that come back.
2Inspectprovisioning_manifestList the item's files and read its licence and declared effects.
3Downloadprovisioning_readName the item and the checksum you expect, and receive the exact bytes.

Your agent reads the results and picks the one that fits the step.

Search the library

Search by describing what the step needs. Each search returns up to 50 references, each with its kind, licence, size and checksum.

MCP tool: intelligence_search, with a query
REST route: POST /api/v1/retrieval
Matching: Lexical, with SQLite FTS5, or hybrid
Results: Up to 50 references per search
In the Workspace: Exact words, or Words and close spellings

MCP requesttools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "intelligence_search",
    "arguments": {
      "query": "CSV validation tool"
    }
  }
}

Library tiers

The library has two tiers, Verified and Community. Searches include community items by default. Pass library_tiers with verified alone to keep a search to verified items.

How review works

Inspect a reference

Before your agent downloads, it can list an item's files with provisioning_manifest and read the facts on the reference: purpose, kind of file, supported kinds of step, licence and declared effects.

Show the source, licence and requirements to the person you work for before the download, as the first-download prompt asks.

Download the exact version

A download names one item by its identity and the checksum you expect. The service rechecks your access and the exact identity, then sends the body checked against its SHA-256.

MCP tool: provisioning_read, with identity and expected_digest
REST routes: POST /api/v1/provisioning and POST /api/v1/download
Inline body: Up to 16 KiB
One download: Up to 1 MiB
Body format: UTF-8 text, or base64 through the protocol

MCP requesttools/call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "provisioning_read",
    "arguments": {
      "identity": "openapi-to-mcp-server",
      "expected_digest": "3f9c1a07…"
    }
  }
}

The Workspace saves a download once its bytes match the reference you selected. A different checksum means the item changed: search again and choose its current version.

Declared effects

Each item declares the effects it needs. Reading files is the default. Send Baltor-Step-Effects to state what a step may do; a file that declares more effects downloads once the step declares them too.

reads_fswrites_fsreads_secretnetworkspawns_process

In the Workspace, a file that declares effects beyond reading asks for your confirmation before it is checked or downloaded.

What counts as a download

One item at the version you selected counts once. Searches, second looks at the same reference and refused downloads are free.

Usage and what you pay for

Read Agent Feeds

Agent Feeds are files your agent reads directly: every source collection as JSON Feed and Markdown, one file per collection, and library updates as JSON, RSS and Markdown.

Bash

# Every source collection
curl https://baltor.ai/feeds/sources.json
 
# Send the last ETag; an unchanged feed answers 304
curl -H 'If-None-Match: "<etag>"' \
  https://baltor.ai/feeds/sources.json

Use Agent Feeds

Need a hand? Status, the connection checklist and the operator's email address are on one page.

Get support