# YTJ Lookup API

> Read-only HTTP API for looking up Finnish companies by name or business ID (Y-tunnus), built on PRH YTJ open data v3. No authentication, no API keys, JSON responses with HATEOAS `_links`, RFC 9457 errors. Production holds the full Trade Register (about 465,000 companies) in Cloudflare D1, refreshed daily from PRH's `all_companies` dump. Data licence CC BY 4.0, source PRH.

Base URL: https://ytj.23signs.org

Three endpoints, all GET. `GET /api/v1/dataset` reports what is loaded (backend, companies, snapshotDate, updatedAt, complete, pending). `GET /api/v1/companies?name=Nokia` searches current and auxiliary names (case-insensitive substring, at least 3 characters, 25 results per page, `page=1..20`, follow `_links.next`; no `totalResults` for name searches in production). `GET /api/v1/companies?businessId=0112038-9` matches an exact business ID. `GET /api/v1/companies/0112038-9` returns one company.

Load status: the register is being loaded into D1 in daily budgeted batches, so for a while `dataset.complete` is false and `dataset.pending` is greater than zero. Every search response and every 404 embeds the `dataset` object; while `complete` is false, a 404 or an empty search can mean "not loaded yet" rather than "does not exist". Check it before concluding. Once complete, a 404 on a valid-looking Y-tunnus means the ID is outside the Trade Register, typically a toiminimi (sole proprietorship), which PRH's register data never covers.

Company fields: `status` is `active` only when PRH's trade register status code is 1, otherwise `not_currently_registered`; `registerStatus` carries the finer PRH REK_KDI code (unregistered, registered, removed_from_register, startup_not_registered, ceased, unknown). The dump has 464,751 companies (462,131 registered); PRH's paginated API reports about 827,000 because it includes historical and removed registrations.

## API

- [OpenAPI 3.1 (YAML)](https://ytj.23signs.org/openapi.yaml): full description of the three endpoints, response schemas, `_links` and problem+json errors
- [OpenAPI 3.1 (JSON)](https://ytj.23signs.org/openapi.json): the same document as JSON
- [Dataset status](https://ytj.23signs.org/api/v1/dataset): what is loaded right now, check this first
- [Search example](https://ytj.23signs.org/api/v1/companies?name=Nokia): companies whose name contains "Nokia"
- [Lookup example](https://ytj.23signs.org/api/v1/companies/0112038-9): Nokia Oyj by business ID (404 with `dataset` until that record is loaded)

## Agent discovery

- [SKILL.md](https://ytj.23signs.org/SKILL.md): agent skill file with when to use, parameters, response and error shapes, limitations, worked examples
- [API catalog (RFC 9727)](https://ytj.23signs.org/.well-known/api-catalog): linkset pointing at the OpenAPI description and the docs
- [ARD manifest](https://ytj.23signs.org/.well-known/ai-catalog.json): Agentic Resource Discovery capability manifest, also at /.well-known/ard.json
- [MCP server card](https://ytj.23signs.org/.well-known/mcp/server-card.json): the two tools with JSON Schema inputs; no hosted MCP transport, tools map to HTTP GET
- [A2A agent card](https://ytj.23signs.org/.well-known/agent-card.json): REST interface, no auth, two read-only skills
- [Agent skills index](https://ytj.23signs.org/.well-known/agent-skills/index.json): points at SKILL.md
- [WebMCP shim](https://ytj.23signs.org/webmcp.js): registers the two tools for a browser agent on the landing page

## Optional

- [README](https://ytj.23signs.org/README.md): architecture (Hono worker, D1 backend with sample fallback, crawler), how to run locally, cost note
- [Landing page](https://ytj.23signs.org/): human search UI
- [Upstream PRH open data](https://avoindata.prh.fi/en/ytj/): the keyless PRH API and daily dump this service is built on