Taxonomies

Manage writable job board taxonomies and read the canonical remote permit and timezone catalogs.

Taxonomies power filters, search landing pages, structured fields, and consistent job data. Skills, categories, and markets are account-specific and writable. Remote permits and timezones are global canonical catalogs and read-only through the Operator API.

Discover taxonomy resources

javascript

1async () => Object.keys(spec.paths).filter((path) =>
2  path.startsWith('/taxonomies')
3)

Use canonical values

Read the relevant resource before creating or updating a job. Reuse existing category, skill, and market slugs. For remote permits and timezones, send only values returned by their read-only catalog endpoints—you cannot create a missing remote permit or timezone through MCP.

List top-level categories

Categories can be nested. Each category returned by GET /taxonomies/categories carries a parentId, which is null for a top-level category. Pass topLevel: 'true' to list only top-level categories, or a category ID as parentId to list that category’s direct children:

javascript

1async () => {
2  const response = await cavuno.request({
3    method: 'GET',
4    path: '/taxonomies/categories',
5    query: { topLevel: 'true' },
6  });
7  return response.data;
8}

topLevel cannot be combined with a parentId category ID; that request returns a 400 error. parentId=null still works as a deprecated alias for topLevel=true. When you also pass search, a page can be short or empty while hasMore is true, so keep paging until hasMore is false.

Rename with care

A slug can be part of public URLs and existing job references. Renames add aliases, but the way a change propagates differs by taxonomy, so inspect the live operation and dependent records before approving it.

Deletion does not clean every reference automatically:

Jobs may retain stale skill slugs after a skill is deleted.
Companies may retain stale market slugs after a market is deleted.
Deleting a category also deletes its direct child categories, but deeper grandchildren remain.

Preview affected records and obtain explicit approval before deleting taxonomy data. A deletion can also remove filters or landing pages from the board.