# Agent Tools

> Data tools for AI agents and developers behind one HTTP API and one MCP server: YouTube transcripts, open jobs from company careers pages, and app store reviews. Results are cached, so repeat requests are answered from the cache.

Base URL: https://api.openkrill.app (this page: https://tools.openkrill.app)

## Tools

Each tool has an HTTP name (used in the route) and an MCP name (used with tools/call).

- `yt-transcripts` (MCP: `get_transcript`): coming soon, not listed by `/v1/tools` or `tools/list` yet. The full transcript of one YouTube video, given a URL or an 11-character video ID. Output is timestamped segments (default), plain text, SRT or VTT. Optional `languages` in priority order and `translateTo`. A video without captions comes back as a result with status "error" and a code, not as an HTTP error. Cached for 30 days.
- `job-boards` (MCP: `list_jobs`): open jobs at companies on Greenhouse, Lever, Ashby, Workable or SmartRecruiters. Input is `companies`, careers page URLs or "ats:slug" tokens such as "greenhouse:airbnb". Optional filters: `keyword`, `location`, `remote`, `department`, `postedSince`, `maxJobsPerCompany`. A board that cannot be read comes back as a record of type "error". Cached for 1 hour.
- `app-reviews` (MCP: `get_app_reviews`): app metadata and recent reviews for Google Play and iOS App Store apps, given store URLs, Apple numeric ids or Play package names. Optional `countries`, `languages`, `maxReviewsPerApp`, `sinceDate` and `sort`. Apple's public review feed is sometimes empty; the result then holds the app row and an error row with code "unavailable". Cached for 6 hours.

## HTTP API

- `GET /v1/tools`: list the tools with their input schemas. No API key needed.
- `GET|POST /v1/tools/{name}/run`: run a tool. GET takes flat query parameters (repeat a key for arrays). POST takes a JSON body.
- `GET /v1/jobs/{id}`: result of a slow request that was answered with HTTP 202.
- `GET /v1/usage`: calls counted for your API key this month (`?period=YYYY-MM` for another month).

Send the key as the `x-api-key` header, or as `Authorization: Bearer <key>`.

Every run response carries `x-cache: HIT`, `MISS` or `STALE`, and a `Server-Timing` header. A request that takes longer than the server's wait budget is answered with HTTP 202, a job id and a poll URL while the work continues; the finished result is then served from the poll URL and from the cache. Rate limits are applied per API key and answered with HTTP 429 and `Retry-After`.

Example:

```
curl -H "x-api-key: $KEY" "https://api.openkrill.app/v1/tools/job-boards/run?companies=greenhouse:airbnb&keyword=engineer&maxJobsPerCompany=5"
```

## MCP

Endpoint: https://api.openkrill.app/mcp (streamable HTTP, stateless: POST one JSON-RPC message or a short batch, get one JSON reply). Tools listed by `tools/list` today: `list_jobs`, `get_app_reviews` (`get_transcript` follows once YouTube transcripts are live). MCP calls wait for the result instead of returning a job id. Use the same API key header.

## Notes

- Error results (a blocked video, a missing job board, an unavailable Apple feed) are returned to the caller but never cached, so the next call retries.
- Reviews returned by `get_app_reviews` carry no reviewer identity.