Cavuno
Sign InStart for free

Embed namespace

Reference for the embeddable jobs response.

Abi Tyas TunggalAJack WalshJ
By Abi Tyas Tunggal and Jack Walsh

Use board.embed.jobs to load compact published-job cards for the public “Powered by Cavuno” embed. The candidate paywall does not gate this response, but board password protection and plan API access still apply.

Shared behavior

The method returns the Board API wire body unchanged and throws BoardApiError for a non-2xx response. Its trailing FetchOptions passes abort signals, headers, and framework cache directives through to fetch.

board.embed.jobs

ts
board.embed.jobs(
  query?: EmbedJobsQuery,
  options?: FetchOptions,
): Promise<ListEnvelope<PublicJobCard>>
FieldTypeBehavior
qstringFree-text query up to 200 characters.
cursorstringOpaque cursor from nextCursor.
limitnumberDefaults to 8; values above 50 are clamped to 50.
offsetnumberJobs to skip. It takes precedence over cursor; offset + limit cannot exceed 10,000.
companyIdstring[]Up to 10 company IDs, matched with OR.
remoteOptionRemoteOption[]on_site, hybrid, or remote.
employmentTypeEmploymentType[]Employment types, matched with OR.
senioritySeniority[]Seniority levels, matched with OR.
locationstringPlace slug for a radius search. An unresolvable place is ignored.
radiusnumber10–250 km; defaults to 50 and is ignored without location.

The response contains object: 'list', url, hasMore, nextCursor, data, and the catalog count, limit, and offset fields when supplied by the API. Each PublicJobCard contains the fields needed for a listing card: identity, title/slug, publish date, employment and remote details, salary, company, categories, skills, and canonical link.

ts
const controller = new AbortController();
const page = await board.embed.jobs(
  {
    q: 'robotics',
    limit: 8,
    offset: 0,
    remoteOption: ['remote', 'hybrid'],
    location: 'london',
    radius: 25,
  },
  { signal: controller.signal },
);


for (const job of page.data) {
  console.log(job.title, job.links.public);
}

Gating and edge behavior

The embed deliberately does not return gatedCount or relatedSearches: candidate-paywall gating and the main job list’s related-search rail do not apply. Do not infer candidate entitlement from the embed response.

Handle:

  • pagination_invalid_cursor or pagination_offset_too_large with status 400.
  • board_password_required with status 401; obtain a board access grant through board.password.verify before retrying.
  • plan_upgrade_required with status 402 when the board plan does not include API access.
  • A missing/private board with status 404.
  • search_unavailable with status 503.

Abort superseded interactive searches with FetchOptions.signal. Use nextCursor only when hasMore is true; an empty data array is a successful result.

  • Use board.jobs.list for the board’s normal candidate-facing catalog, including paywall counts and related searches.
  • Use board.jobs.retrieve for the canonical job detail after a user follows a card link.
  • Use board.password.verify when a password-protected board returns board_password_required.