# SearchRight Engine — API for LLMs

> Korean recruiting brief → company search engine. External API surface for partner integrations (sourcing pipelines / CRM / AI agents).
>
> 이 파일은 [llms.txt 표준](https://llmstxt.org/) — partner LLM (Cursor / Copilot / Codex 등) 이 SearchRight API 통합 시 빠르게 컨텍스트 잡도록. SEO 효과보다 DX 가 주 목적.

## Auth & access

- [External API guide](/docs/api/external) — Bearer key (`srk_live_<32B>`), scopes (`search:read` initial), per-key rate limit (DB sliding window, default 60 rpm), error codes (401 / 403 / 429 / 5xx).
- [OpenAPI 3.1 spec (machine-readable)](/api/v1/openapi.json) — request/response schemas, error shapes, examples.

## Endpoints (v1)

- [POST /api/v1/search](/docs/api/external) — natural-language company search. Internal pipeline (HyDE + structured filter + Cohere rerank). Stable v1 subset (no internal score/cost). Body: `{ query: string, limit?: 1-100 }`. Response: array of `{ id, name, name_ko, name_en, domain, ... }`.

## Errors (standard shape)

All v1 errors return:
```json
{ "error": { "code": "<code>", "message": "<human-readable>", "details"?: {...} } }
```
Codes: `invalid_request` (400) / `unauthorized` (401) / `forbidden` (403) / `not_found` (404) / `rate_limit_exceeded` (429) / `internal_error` (500) / `upstream_error` (502) / `service_unavailable` (503).

## Versioning

`/api/v1/*` = stable. Breaking changes ship as `/api/v2/*`. Deprecations announced ≥ 30 days ahead in [`docs/api/external.md`](/docs/api/external).

## For SearchRight engineers (internal)

- [Project onboarding](/docs/onboarding) — 30-min context for new engineers (project / stack / first PR path).
- [Agent rules index](/docs/agent-rules/_index) — 5-category rules SSOT (core / process / search-quality / enrich-pipeline / archive).
- [Mission queue](/docs/plans/NEXT) — what's next.
- [Handoff vision](/docs/context/handoff-vision) — north star for self-sustaining agent harness.

## License & contact

Repo private. Partner inquiries → SearchRight team direct.