# Trawle API reference

Base URL: `https://trawle.com`. Version 1.0.0.

Open jobs straight from employers' own applicant tracking systems, verified daily, with closure and repost history.

- Data refreshes once a day; polling more often returns the same results.
- Build a `JobQuery` from ids: resolve place names with `GET /v1/places`, roles with `GET /v1/roles`, companies with `GET /v1/companies`.
- For a daily "new jobs" check, pass the previous response's `nextSince` as `postedSince`.
- Results link to the employer's posting (`applyUrl`) and to Trawle (`url`). Show "Data by Trawle" with a link when you display them.
- Full job descriptions are not served; link to `applyUrl`.

## Jobs

- [Search open jobs](https://developers.trawle.com/api/search-jobs.md): `POST /v1/jobs/search`
- [Check whether jobs are still open](https://developers.trawle.com/api/check-job-status.md): `POST /v1/jobs/status`
- [Get a job](https://developers.trawle.com/api/get-job.md): `GET /v1/jobs/{id}`

## Meta

- [Index size and freshness](https://developers.trawle.com/api/get-stats.md): `GET /v1/stats`

## Companies

- [Get a company and its hiring activity](https://developers.trawle.com/api/get-company.md): `GET /v1/companies/{slug}`
- [Find companies by name or domain](https://developers.trawle.com/api/search-companies.md): `GET /v1/companies`

## Lookups

- [Find places (GeoNames) for the `places` filter](https://developers.trawle.com/api/resolve-location.md): `GET /v1/places`
- [Find roles for the `roles` filter](https://developers.trawle.com/api/find-roles.md): `GET /v1/roles`
- [List job families for the `families` filter](https://developers.trawle.com/api/list-families.md): `GET /v1/families`

Base URL: `https://trawle.com`. JSON in, JSON out. OpenAPI 3.1 spec: [/openapi.json](https://developers.trawle.com/openapi.json).

## About the API

Open jobs straight from employers' own applicant tracking systems, verified daily, with closure and repost history.

- Data refreshes once a day; polling more often returns the same results.
- Build a `JobQuery` from ids: resolve place names with `GET /v1/places`, roles with `GET /v1/roles`, companies with `GET /v1/companies`.
- For a daily "new jobs" check, pass the previous response's `nextSince` as `postedSince`.
- Results link to the employer's posting (`applyUrl`) and to Trawle (`url`). Show "Data by Trawle" with a link when you display them.
- Full job descriptions are not served; link to `applyUrl`.

## Authentication

No key is needed yet, and any origin may call the API from a browser. API keys and OAuth are coming soon; the free tier is planned at about 1,000 requests a day, with attribution.

## Errors

Every error has the same shape, `{ error: { code, message, hint?, issues? } }`. See [Errors](https://developers.trawle.com/guides/errors).