---
title: "Search executable and requestable tools"
method: POST
path: "/credits/tools/search"
tags: ["Catalog"]
---

# Search executable and requestable tools

`POST /credits/tools/search`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/credits/tools/search`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

REST counterpart to MCP search_apis. Returns compact ranked summaries and routes a selected result through /credits/tools/describe. Workspace and agent principals see enabled and requestable disabled tools by default; end-user-bound callers see enabled tools only, and an account setting may choose enabled-only discovery. Results honor key endpoint allowlists, agent-connection scopes, and end-user policies. Secret keys require tenant:read rather than credits:move. This operation does not call a provider or burn credits.

## Headers

- `X-Locus-Session-Id` string
- `X-Locus-End-User` string: Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.

## Request body

- object
  - `query` string: Trimmed natural-language capability, provider, or tool query. Optional with category or pack.
  - `category` string: Live canonical category ID or unambiguous alias.
  - `pack` string: Live curated-pack ID or unambiguous alias.
  - `limit` integer
  - `cursor` string
  - `include_facets` boolean

## Response `200`

Ranked compact tool summaries

- ToolSearchResponse
  - `success` unknown, required
  - `query` string, required
  - `taxonomy_revision` string, required
  - `appliedFilters` object
  - `count` integer, required
  - `next_cursor` string
  - `facets` object[]
  - `results` ToolSearchMatch[], required
    - `slug` string, required
    - `tool` string, required
    - `provider` string, required
    - `endpoint` string, required
    - `title` string, required
    - `enabled` boolean, required
    - `description` string, required
    - `category` string
    - `category_ids` string[], required
    - `pack_ids` string[], required
    - `credits` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
    - `variableCost` unknown
    - `pricing` object, required
      - `type` 'fixed' | 'variable', required
      - `credits` string, required: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `min_credits` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `max_credits` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `cap_credits` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
      - `typical_credits` unknown
    - `next_step` object, required
      - `method` 'POST', required
      - `path` '/api/credits/tools/describe' | '/api/credits/tools/access-requests', required
      - `body` object, required
        - `slug` string, required
        - `operation_query` string
  - `note` string: Present when no enabled tool matched.

## Other responses

- `400`: Invalid search scope, group, or scoped cursor
- `401`: Missing or invalid execution credential
- `500`: Tool search failed

---

[API](https://skmtc.dev/paywithlocus/apis/locus-pro-api.md) - [All operations](https://skmtc.dev/paywithlocus/apis/locus-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paywithlocus/apis/locus-pro-api/revisions/aab8fa5d6cef?raw)