# Discover job families and allowed filter values

`GET https://trawle.com/v1/taxonomy`

Static family slugs and fixed enums from the same bundled taxonomy and JobQuery schema used by search. Use GET /v1/families when live open-job counts are needed. No database or model calls.

## Authentication

- Header `x-api-key`: Read-only API key from https://trawle.com/account#api-keys. 1,000 requests per daily window. Anonymous requests are also supported with a per-IP limit.

## Responses

### 200: Families and filter values.

Schema: SearchOptions

- `families` (array<object>, required, TaxonomyFamily)
  - `slug` (string, required)
  - `name` (string, required)
  - `description` (string, required)
- `filters` (object, required)
  - `seniority` (array<string>, required): One of: `intern`, `entry`, `mid`, `senior`, `lead`, `principal`, `director`, `vp`, `executive`.
  - `employment` (array<string>, required): One of: `full_time`, `part_time`, `contract`, `temporary`, `internship`, `apprenticeship`, `seasonal`, `volunteer`.
  - `workplace` (array<string>, required): One of: `remote`, `hybrid`, `onsite`.
  - `posted` (array<string>, required): One of: `1d`, `3d`, `7d`, `30d`.
  - `sort` (array<string>, required): One of: `newest`, `pay`.
  - `currency` (array<string>, required): One of: `USD`, `EUR`, `GBP`, `DKK`, `SEK`, `NOK`, `CHF`, `CAD`, `AUD`.
  - `pay` (array<string>, required): One of: `listed`.
  - `reposts` (array<string>, required): One of: `hide`, `only`.
  - `agencies` (array<string>, required): One of: `include`, `only`.

### 401: Invalid, expired or revoked API key.

Schema: Error

- `error` (object, required)
  - `code` (string, required): Machine-readable: `invalid_request`, `not_found`, `forbidden`, `rate_limited`, `internal`. Example: `invalid_request`.
  - `message` (string, required): Example: `places: expected an array of GeoNames ids`.
  - `hint` (string, optional): What to do next, e.g. which lookup to call first. Example: `Resolve place names to ids with GET /v1/places?q=`.
  - `issues` (array<object>, optional): Validation problems, one per invalid field.
    - `path` (string, required)
    - `message` (string, required)

### 429: Rate limit reached. Respect Retry-After and cache results.

Schema: Error

- `error` (object, required)
  - `code` (string, required): Machine-readable: `invalid_request`, `not_found`, `forbidden`, `rate_limited`, `internal`. Example: `invalid_request`.
  - `message` (string, required): Example: `places: expected an array of GeoNames ids`.
  - `hint` (string, optional): What to do next, e.g. which lookup to call first. Example: `Resolve place names to ids with GET /v1/places?q=`.
  - `issues` (array<object>, optional): Validation problems, one per invalid field.
    - `path` (string, required)
    - `message` (string, required)

## Examples

### cURL

```bash
curl "https://trawle.com/v1/taxonomy" \
  -H "x-api-key: $TRAWLE_API_KEY"
```

### TypeScript

```ts
import createClient from "openapi-fetch";

// npx openapi-typescript https://developers.trawle.com/openapi.json -o trawle.d.ts
import type { paths } from "./trawle";

const trawle = createClient<paths>({
  baseUrl: "https://trawle.com",
  headers: { "x-api-key": process.env.TRAWLE_API_KEY },
});

const { data, error } = await trawle.GET("/v1/taxonomy");
```

### Python

```python
import os
import requests

response = requests.get(
    "https://trawle.com/v1/taxonomy",
    headers={"x-api-key": os.environ["TRAWLE_API_KEY"]},
)
response.raise_for_status()
data = response.json()
```

### Response 200

```json
{
  "families": [
    {
      "slug": "string",
      "name": "string",
      "description": "string"
    }
  ],
  "filters": {
    "seniority": ["intern"],
    "employment": ["full_time"],
    "workplace": ["remote"],
    "posted": ["1d"],
    "sort": ["newest"],
    "currency": ["USD"],
    "pay": ["listed"],
    "reposts": ["hide"],
    "agencies": ["include"]
  }
}
```

### Response 401

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Sign in to use this",
    "hint": "Sign in at /sign-in; requests carry the session cookie."
  }
}
```

### Response 429

```json
{
  "error": {
    "code": "invalid_request",
    "message": "places: expected an array of GeoNames ids",
    "hint": "Resolve place names to ids with GET /v1/places?q=",
    "issues": [
      {
        "path": "string",
        "message": "string"
      }
    ]
  }
}
```