Jobs

Discover, create, update, publish, pause, expire, duplicate, delete, and batch-process jobs through the Cavuno MCP server.

By Abi Tyas Tunggal and Jack Walsh

Use the jobs resource to operate the full job lifecycle from an MCP client. The exact request fields and transitions are defined by the live OpenAPI document, so search the specification before writing data.

Discover the available job operations

Tool: search

javascript

1async () => Object.entries(spec.paths)
2  .filter(([path]) => path.startsWith('/jobs'))
3  .map(([path, methods]) => ({ path, methods: Object.keys(methods) }))

List published jobs

Tool: execute

javascript

1async () => {
2  const response = await cavuno.request({
3    method: 'GET',
4    path: '/jobs',
5    query: { status: 'published', limit: 25 },
6  });
7  return response.data;
8}

Job statuses

A job’s status is one of draft, published, expired, archived, or pending_approval. Filter the list with query: { status: 'pending_approval' } to read the jobs awaiting your approval. A draft filter does not include them.

A pending_approval job is waiting for an operator to approve it. It is not public, just like a draft. Approve it with POST /jobs/{id}/publish, or reject it with DELETE /jobs/{id}. You cannot create a job in pending_approval or set it directly: a job enters this status when your board requires approval for backfilled jobs or for free job posts.

Avoid duplicate jobs

POST /jobs returns a 409 jobs_already_exists error when the new job matches a job already on your account. details.existing_job_id is the matching job, and details.matched_on says which check matched:

`matched_on`	Matches when	Can be overridden
`external_id`	Another job has the same `externalId`.	No
`application_url`	Another job uses the same application URL or email.	Yes, with `allowSharedApplicationUrl: true`
`composite_hash`	Another job has the same company, title, location, and description.	No

Always set externalId to the source job URL or ATS requisition ID, so a repost of the same role is detected reliably.

Several different roles often share one ATS page or one application inbox. When matched_on is application_url, details.matching_jobs lists up to 5 jobs that use the same application URL or email, each as { id, title, status }. If the new job is a different role, retry the create with allowSharedApplicationUrl: true. The flag skips only the application URL check; an externalId match or an identical job still returns 409. The retry is a different request body, so send a new Idempotency-Key if you used one. The same flag works on a create inside POST /jobs/batch.

javascript

1async () => {
2  const response = await cavuno.request({
3    method: 'POST',
4    path: '/jobs',
5    body: {
6      // Resend every field from the first request, then add the flag.
7      title: 'Faculty Position in AI and Analytics',
8      applicationUrl: 'recruitment@example.edu',
9      externalId: 'REQ-2027-14',
10      allowSharedApplicationUrl: true,
11    },
12  });
13  return response;
14}

In the CLI, pass --external-id and --allow-shared-application-url to cavuno jobs create.

Write safely

Read the current record and the request schema before creating or patching a job. Keep bulk operations within the documented limit of 100 operations, inspect every per-operation result, and verify the persisted record after a write. Start with post a job, and use the API reference for every field and batch operation.