boxel-api

Boxel API

Canonical home for Boxel platform API knowledge.

Architectural principle: boxel-cli owns the entire Boxel API surface. Any code that talks to the realm server or Matrix lives in boxel-cli; consumers (the software-factory, custom scripts, hand-written tools) import BoxelCLIClient from @cardstack/boxel-cli/api and call its methods. Auth (tokens, refresh, retries) is fully internal — if you're holding a JWT or calling fetch against a realm URL directly, you're in the wrong layer.

import { BoxelCLIClient } from '@cardstack/boxel-cli/api';

let client = new BoxelCLIClient(); // reads the active Boxel profile

All examples below assume client is a BoxelCLIClient instance.

Federated search

Search across one or more realms via /_federated-search. Query syntax matches the Boxel realm search format.

CLI

boxel search --realm <realm-url> [--realm <realm-url>...] --query '<json>'

--realm is repeatable. --query takes a JSON string. Append --json for raw output.

Programmatic

let result = await client.search(realmUrl, query); // single realm
let result = await client.search([realmA, realmB], query); // federated

Returns { ok, status, data?, error? }. data is an array of card resources.

Query syntax

{
  "filter": { ... },
  "sort": [ ... ],
  "page": { "size": 10 }
}

All top-level fields are optional. An empty query {} returns all cards in the targeted realms.

Filter by card type

{
  "filter": {
    "type": {
      "module": "http://localhost:4201/software-factory/darkfactory",
      "name": "Project"
    }
  }
}

Returns all cards that adopt from (or extend) the specified type. Wildcards (*) in module or name are not supported — always use a specific CodeRef.

Filter by field value (eq)

eq requires an on to scope the field to a card type:

{
  "filter": {
    "on": { "module": "...", "name": "Issue" },
    "eq": { "status": "in_progress" }
  }
}