Global search API reference

Global search answers one question for an operator: "where is this name, symbol, or address in the system I am working in?" Instead of calling each resource endpoint on its own and stitching the results together, you send one query and read back a single response grouped into sections, one per resource type. The Console search palette uses this endpoint, and you can call it directly to build the same experience in your own application.

This surface is read-only. It returns matches that already exist. It does not create, change, or delete anything.

Endpoint

The endpoint uses the single-resource envelope: data holds the result, and links.self echoes the request path. The active organisation and system context bound every search, as described in Organization and system scope.

Query parameters

The query and its limits are nested under a query object, so each parameter is sent with bracket notation.

A term shorter than 2 characters or longer than 120 is rejected before the search runs, so a single keystroke does not trigger a backend call. Each section has its own limit, so you can ask for more tokens than users in the same request without changing the others.

Response sections

The response is a list of sections, one per result type. A section appears only when it has at least one match, so an empty category is left out rather than returned as an empty array. Each section carries a type and a homogeneous items list.

Read the type field to decide how to render each section, rather than relying on position. When no section matches, data.sections is an empty list.

What each section returns

Each section is scoped to what the caller is allowed to see, so two operators running the same query in the same system can get different results.

Contacts

Contacts come from the caller's own address book in the active organisation. The match runs against contact names and wallet addresses, and never reaches another user's address book. Each item carries the contact id, name, and wallet.

Tokens

Token results depend on the caller's roles. A user who holds any system role sees token matches from across the active system. A user with no system role sees only the tokens they actually hold in that system. The match runs against token name, symbol, and address. Each item carries the token's identifying fields, including its address id, name, and symbol. For the full token shape, see the token endpoints.

Users

User results appear only when the caller holds the user-search permission. The match runs against user name and wallet. Each item carries the user id, name, wallet, signingAddress, executorAddress, and role.

When the term is a wallet address that does not match a user directly, the platform resolves it through the on-chain identity registry and returns the user who owns that identity. An address pasted from an event therefore still resolves to a name. When the term matches the caller's own name, email, wallet, or role, the caller is placed at the top of the user results.

System contracts

System contracts are the indexed contracts that make up a system, such as token factories, registries, and compliance modules. The platform surfaces them so a client can put a readable label on a raw address that an operator meets in an event but that belongs to no token, account, or contact. Each item carries the contract id (lowercased address), a human-readable name, and a contractType.

Run a search

GET /api/v2/search-results runs the search and returns the matching sections.

curl --globoff "https://your-platform.example.com/api/v2/search-results?query[query]=bond" \
  -H "x-api-key: YOUR_API_KEY"

{
  "data": {
    "sections": [
      {
        "type": "contacts",
        "items": [
          {
            "id": "8a3b8a14-8d50-4a52-a7db-2f4a7c2a8e5f",
            "name": "Northwind Treasury",
            "wallet": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
          }
        ]
      },
      {
        "type": "tokens",
        "items": [
          {
            "id": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
            "name": "Series A Bond",
            "symbol": "BOND"
          }
        ]
      },
      {
        "type": "systemContracts",
        "items": [
          {
            "id": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
            "name": "Bond Factory",
            "contractType": "BondFactory"
          }
        ]
      }
    ]
  },
  "links": {
    "self": "/v2/search-results"
  }
}

To cap a single section, add its limit. This request asks for up to 25 token matches and leaves the other sections at their default of 10.

curl --globoff "https://your-platform.example.com/api/v2/search-results?query[query]=treasury&query[limits][tokens]=25" \
  -H "x-api-key: YOUR_API_KEY"

When to use it

Use this endpoint when you need to:

• Build a search box or command palette that finds contacts, tokens, users, and system contracts in one call.
• Turn a raw address from an event or a transaction into a readable label, whether it belongs to a contact, a user, a token, or a system contract.
• Offer autocomplete that respects each operator's permissions without writing the section-by-section permission logic yourself.

To search one resource type with full filtering, sorting, and pagination instead, use that resource's list endpoint, such as address book contacts or the token endpoints. To use the same search from the Console, see Global search.