---
title: "Search candidate parts"
method: POST
path: "/api/v1/tools/search_candidates"
tags: ["Agent tools"]
---

# Search candidate parts

`POST /api/v1/tools/search_candidates`

## Request

- Base URL: `https://parts.skoia.me`
- URL: `https://parts.skoia.me/api/v1/tools/search_candidates`
- Auth: none declared

Searches the verified local index for candidates; a candidate is never presented as an identified product without evidence.

## Request body

- object
  - `query` string, required
  - `limit` integer

## Response `200`

Structured tool result

- object
  - `schemaVersion` unknown, required
  - `tool` string, required
  - `requestId` string, required
  - `status` 'OK' | 'NEEDS_INPUT' | 'BLOCKED' | 'UNAVAILABLE', required
  - `facts` object[], required
  - `confidence` object, required
    - `score` number, nullable, required
    - `level` 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN', required
    - `reason` string, nullable
  - `provenance` object[], required
    - `type` string, required
    - `source` string, nullable
    - `retrieved_at` string, nullable
    - `verification_status` string, nullable
  - `warnings` string[], required
  - `data` object, required

## Other responses

- `4XX`: Machine-readable client error
- `5XX`: Machine-readable transient or provider error

---

[API](https://skmtc.dev/skoia/apis/skoia-parts-agent-api.md) · [All operations](https://skmtc.dev/skoia/apis/skoia-parts-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skoia/apis/skoia-parts-agent-api/revisions/cdad8c14db92?raw)