Aptora for AI assistants

List all of the signed-in user's CVs (id, name, theme).

Takes no arguments.

Fetch a single CV including its full resume data, plus `profile_skills`: the canonical skills detected on it, with the `skill_id` list_jobs filters by.

• cv_id · string · required — Opaque, stable object reference. Use the slug returned by the API.

Return the full AptoraCV resume JSON Schema that CV `data` must conform to. Prefer this over the `aptora://cv-schema` resource — it is a plain tool call and works on every client.

Takes no arguments.

What this server can store: the supported AptoraCV sections, the section/field aliases it accepts, the allowed enum values and the supported import features (strict, merge, normalization). Call this before importing a resume from another format.

Takes no arguments.

Create a CV from a COMPLETE AptoraCV document; preserve all populated fields and entries. Call `get_cv_schema` and dry-run `validate_cv` first. Aliases normalize automatically; strict=true rejects entry loss. Unknown fields are rejected with a correction hint. PERSONAL workspace identity: firstName/lastName/name always become the signed-in account's name, discarding the submitted candidate name. Other data is preserved; `normalized` reports rule `personal_workspace_identity`. Import into a TEAM workspace to preserve someone else's name.

• data · object · required — Complete AptoraCV document: preserve ALL populated fields and array entries. Stored section counts are echoed for verification. Below is a one-level outline; call `get_cv_schema` for exact nested fields, types and enums, then `validate_cv` to dry-run before writing.
• strict · boolean — If true, reject the entire import when stored entry counts are lower than received. Default false: write and report differences. Unknown AptoraCV fields are always rejected.
• normalize · boolean — Normalize section/field aliases and enum wording before validation (work→employment, startDate→start, master→Expert). Default true; every change is listed in `normalized`.
• name · string · required — A name/label for the CV.
• theme · string — Optional theme id. Omitted, the CV starts on the workspace's default profile theme (settings, 'Profiles').

Update a CV's name, data and/or theme. Only provided fields change. By default `data` REPLACES the stored document, so any section you omit is lost — pass merge=true to patch the stored CV instead (sections you send replace their counterpart, sections you omit are kept). The response reports received vs. stored counts per section. In a PERSONAL workspace the candidate name is always the signed-in account's — see create_cv.

• data · object — Complete AptoraCV document: preserve ALL populated fields and array entries. Stored section counts are echoed for verification. Below is a one-level outline; call `get_cv_schema` for exact nested fields, types and enums, then `validate_cv` to dry-run before writing.
• strict · boolean — If true, reject the entire import when stored entry counts are lower than received. Default false: write and report differences. Unknown AptoraCV fields are always rejected.
• normalize · boolean — Normalize section/field aliases and enum wording before validation (work→employment, startDate→start, master→Expert). Default true; every change is listed in `normalized`.
• cv_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• name · string
• theme · string
• merge · boolean — Merge `data` into the stored document instead of replacing it. Objects merge recursively; a list or scalar you send replaces the stored one. Default false.

Dry-run: validate a AptoraCV resume document WITHOUT writing anything. Returns whether it is valid, any schema errors, the normalization it would apply, how many entries each section would store versus how many you sent, and any field that is not part of AptoraCV. Use this before create_cv/update_cv to confirm no data is lost. In a PERSONAL workspace the reported normalization includes the identity binding the write would apply, so this dry run and the write agree.

• data · object · required — Complete AptoraCV document: preserve ALL populated fields and array entries. Stored section counts are echoed for verification. Below is a one-level outline; call `get_cv_schema` for exact nested fields, types and enums, then `validate_cv` to dry-run before writing.
• strict · boolean — If true, reject the entire import when stored entry counts are lower than received. Default false: write and report differences. Unknown AptoraCV fields are always rejected.
• normalize · boolean — Normalize section/field aliases and enum wording before validation (work→employment, startDate→start, master→Expert). Default true; every change is listed in `normalized`.

Delete (soft-delete) a CV by id.

• cv_id · string · required — Opaque, stable object reference. Use the slug returned by the API.

Find roles and ESCO groups by German/English name or ISCO code. Use job_title_id or esco_uri with list_jobs; ESCO includes descendants.

• query · string · required
• limit · integer

Search jobs using an active job_title_id, esco_uri or at least 1 skill id. search_job_roles supplies selectable roles and ESCO concepts. ESCO includes descendants; role/ESCO and skill filters intersect. Skills match any selected id, ranked by overlap then recency; role-only uses recency. Skill IDs: get_cv profile_skills or listing required_skills. Summaries include skills; do not crawl rows with get_job, which is for a listing the user selected. Bare searches stop at page 10; ESCO keeps this cap even with extra filters. Pages and foreign listing details share account/workspace fair-use budgets across REST and MCP; refusals include retry_after seconds (§17).

• skills · array<string> — At least 1 skill id without role/ESCO; otherwise optional. A listing matches when it requires any selected skill.
• job_title_id · string — Opaque, stable object reference. Use the slug returned by the API.
• esco_uri · string — ESCO concept from search_job_roles, including descendants.
• type · enum — Only freelance or only permanent positions.
• title · string — Substring filter on the job title.
• company · string — Substring filter on the company.
• location · string — Substring filter on the location.
• page · integer — 1-based page number (default 1).
• page_size · integer — Jobs per page (default 20, max 50).

Fetch one job listing including the full job spec, its `required_skills` (with the `skill_id` list_jobs filters by) and the application contact (contact_email/contact_person) when the listing carries one. For one listing the user singled out: a list_jobs result already opens each of its rows in place, so fetching a page row by row stacks up one card per job and says nothing the list did not. Listings of other workspaces are subject to a fair-use read budget of distinct listings per hour and day; re-reading one is free, and a refusal carries `retry_after` in seconds. Fair use is what the terms of service set out in § 17.

• job_id · string · required — Opaque, stable object reference. Use the slug returned by the API.

Apply to a job with one of the user's CVs. The listing's `origin` (from get_job) decides what happens: a `team` listing is DELIVERED into the owning workspace — `email` comes back null, there is nothing left for the user to send, and a contact_email passed for it is ignored. An `external` listing composes an application email (Gmail compose URL + markdown template) addressed to the listing's contact instead — nothing is sent; if it carries no contact_email, ask the user for the recipient and pass contact_email. IMPORTANT: applying PUBLISHES the chosen CV at a public share link anyone can open, and visits to it are tracked. Ask the user for explicit confirmation and pass confirm_publish=true only after they agreed.

• job_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• cv_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• theme · enum — Theme for the shared CV link (default: the CV's theme).
• day_rate · integer — Offered day rate in EUR (freelance jobs only).
• contact_email · string — Recipient for an `external` listing — required if it carries no contact_email; ignored for a `team` listing.
• contact_person · string — Contact person for the salutation (optional).
• confirm_publish · boolean · required — Must be true; confirms the user agreed to publishing their CV at a public, visit-tracked link.

List the workspace's job applications, newest first, each with its composed application email — null for one delivered into a team workspace, whose `status` says where it stands instead. Readable in every workspace; whether NEW ones may be made is apply_to_job's question (a personal workspace or a consultancy team, never a company/agency team).

Takes no arguments.

The field schema for creating/updating a job listing. Static — call it before the first write instead of guessing field names.

Takes no arguments.

Dry-run a listing: what is missing or ignored; writes nothing. Use before create_job. Every plan; detect_skills needs one with skill detection.

• title · string · required — The listing's headline, e.g. 'Platform Engineer'. Write the role — not an ad subject line with location, duration or reference number in it. The role behind the taxonomy is named by the detection run reading the whole spec, so a headline never has to carry it.
• company · string · required — Hiring company.
• type · enum · required — Engagement type.
• published_since · string · required — ISO date the listing went live.
• job_spec · string — The full job description. This is what the required skills are detected from — a listing without it will not match any candidates.
• location · string
• remote_in_percent · integer — Share of remote work. 0-100.
• start_date · string — ISO date.
• end_date · string — ISO date — only when the ad names an actual date. Most ads state a duration instead; that belongs in duration_months, never computed into a date here.
• duration_months · integer — Stated engagement length in months, e.g. 12 for '12 MM'. 1-60.
• duration_open_ended · boolean — True when the duration carries a '+'/'++'/'mit Option auf Verlaengerung' — the ad says the length is open upward. It qualifies duration_months and needs one: a create without a duration drops it, an update without one is refused.
• dayrate · integer — EUR/day (freelance). 0-10000.
• salary · integer — EUR/year (permanent). 0-10000000.
• job_url · string — Absolute http(s) URL of the advertisement.
• contact_email · string
• contact_person · string
• expires_at · string — ISO datetime the listing stops being shown. Omit it and the listing does not expire; send null on an update to remove a deadline set earlier.
• stated_skills · array<object> — See create_job.
• detect_skills · boolean — Also report the skills job_spec would be matched on. Runs the detector. Off by default.

Create a listing of this team workspace. Starts PRIVATE (off the board, no matching) until publish_job. Free on every team plan; skill detection only if the plan includes it.

• title · string · required — The listing's headline, e.g. 'Platform Engineer'. Write the role — not an ad subject line with location, duration or reference number in it. The role behind the taxonomy is named by the detection run reading the whole spec, so a headline never has to carry it.
• company · string · required — Hiring company.
• type · enum · required — Engagement type.
• published_since · string · required — ISO date the listing went live.
• job_spec · string — The full job description. This is what the required skills are detected from — a listing without it will not match any candidates.
• location · string
• remote_in_percent · integer — Share of remote work. 0-100.
• start_date · string — ISO date.
• end_date · string — ISO date — only when the ad names an actual date. Most ads state a duration instead; that belongs in duration_months, never computed into a date here.
• duration_months · integer — Stated engagement length in months, e.g. 12 for '12 MM'. 1-60.
• duration_open_ended · boolean — True when the duration carries a '+'/'++'/'mit Option auf Verlaengerung' — the ad says the length is open upward. It qualifies duration_months and needs one: a create without a duration drops it, an update without one is refused.
• dayrate · integer — EUR/day (freelance). 0-10000.
• salary · integer — EUR/year (permanent). 0-10000000.
• job_url · string — Absolute http(s) URL of the advertisement.
• contact_email · string
• contact_person · string
• expires_at · string — ISO datetime the listing stops being shown. Omit it and the listing does not expire; send null on an update to remove a deadline set earlier.
• stated_skills · array<object> — [{name, requirement?, evidence?}] as the ad says; no detection runs. Pick unclear_skills by {skill_id}; unknown_skills are not created.

Update a listing of this workspace; only named fields change, null clears one. Saving never re-detects skills: pass detect_skills=true after a spec change. stated_skills only adds.

• job_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• title · string — The listing's headline, e.g. 'Platform Engineer'. Write the role — not an ad subject line with location, duration or reference number in it. The role behind the taxonomy is named by the detection run reading the whole spec, so a headline never has to carry it.
• company · string — Hiring company.
• type · enum — Engagement type.
• published_since · string — ISO date the listing went live.
• job_spec · string | null — The full job description. This is what the required skills are detected from — a listing without it will not match any candidates.
• location · string | null
• remote_in_percent · integer | null — Share of remote work. 0-100.
• start_date · string | null — ISO date.
• end_date · string | null — ISO date — only when the ad names an actual date. Most ads state a duration instead; that belongs in duration_months, never computed into a date here.
• duration_months · integer | null — Stated engagement length in months, e.g. 12 for '12 MM'. 1-60.
• duration_open_ended · boolean — True when the duration carries a '+'/'++'/'mit Option auf Verlaengerung' — the ad says the length is open upward. It qualifies duration_months and needs one: a create without a duration drops it, an update without one is refused.
• dayrate · integer | null — EUR/day (freelance). 0-10000.
• salary · integer | null — EUR/year (permanent). 0-10000000.
• job_url · string | null — Absolute http(s) URL of the advertisement.
• contact_email · string | null
• contact_person · string | null
• expires_at · string | null — ISO datetime the listing stops being shown. Omit it and the listing does not expire; send null on an update to remove a deadline set earlier.
• stated_skills · array<object> — See create_job.
• detect_skills · boolean — Also re-detect the skills of the saved spec; spends one detection run. Off by default.

Delete one of this workspace's job listings. Refused while candidates are still waiting on it — the refusal says how many; repeat the call with reject_open_applications=true to delete anyway.

• job_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• reject_open_applications · boolean — Reject every application still waiting on this listing and delete it. Each of those candidates is notified that their application was rejected. Off by default: without it a listing with open applications is not deleted.

Put one of this workspace's listings on the public board and into candidate matching. Reversible with unpublish_job — the listing keeps its id, its skills and its match history either way.

• job_id · string · required — Opaque, stable object reference. Use the slug returned by the API.

Take one of this workspace's listings back off the public board and out of candidate matching. The listing itself stays.

• job_id · string · required — Opaque, stable object reference. Use the slug returned by the API.

Set how strongly a listing asks for a linked skill: required, optional or unspecified (not stated, or undo). skill_id from get_job's required_skills. Kept as a decision; later detection never replaces it. Weights matching; existing searches keep their scores (see basis_status).

• job_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• skill_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• requirement · enum · required
• expected_requirement_revision · string — The requirement_revision you last read for this skill. With it, a classification somebody else changed in between is refused (conflict) instead of overwritten. Optional.

The listings this workspace owns, including expired ones. Different from list_jobs, which is the public board.

• page · integer
• page_size · integer — Default 20, max 50.

Find candidates for a job (job_id) or for free criteria (filters) across every profile whose owner opted into being found. Ranks them by skill overlap plus a small role bonus and returns the evidence behind each score. Every search needs an anchor: a job_id (one of this workspace's listings, whose detected skills are the requirements) or at least 3 ids of active skills in the filters — those are what a candidate is ranked against. Every filter EXCLUDES on top of that: skills, titles, country, remote share and day rate each narrow the set, and no score buys a candidate back in. Within one list any entry counts, across lists all of them must. Skill ids come from a listing's required skills or a search result; an id that names no active skill is refused. This is DETERMINISTIC — it runs no model and forms no opinion beyond the counted overlap; call refine_search afterwards if you want that. Results never contain contact data — use send_outreach to reach someone. If the run comes back pending, poll get_search with the returned run_id. Runs and delivered profiles are subject to a fair-use read budget — fair use is what the terms of service set out in § 17 — and a refusal carries `retry_after` in seconds.

• job_id · string — Opaque, stable object reference. Use the slug returned by the API.
• filters · object
• force · boolean — Re-run instead of reusing.

Have a model estimate how well the candidates a finished search found fit, from their careers: seniority against the role, how central the matching skills are to what someone actually does, whether the role plausibly interests them, and whether the missing skills are the kind one picks up. Re-ranks the SAME candidates — it never adds or removes anyone, and it never re-scores the counted overlap. Optional 'focus' is what matters beyond the listing ("must have worked in a regulated environment"). Costs one AI step from the workspace allowance; asking the same thing of the same run again is free. Poll get_search and read refine_status.

• run_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• focus · string — Optional. What to weigh beyond the listing itself.
• force · boolean — Estimate again instead of reusing.

Status and a page of results for a run started by search_candidates. 'status' is the search itself; 'refine_status' is the optional AI fit estimate and is null until refine_search is called. Results are complete and ranked either way — a failed estimate leaves them untouched. Paging costs no allowance.

• run_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• page · integer
• page_size · integer — Default 25, max 100.

This workspace's candidate searches, newest first, one page at a time.

• page · integer
• page_size · integer — Default 20, max 50.

Save a candidate to the workspace shortlist, optionally against a job. The shortlist belongs to the whole team.

• cv_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• job_id · string — Opaque, stable object reference. Use the slug returned by the API.
• note · string

The workspace shortlist, optionally filtered by job, one page at a time.

• job_id · string — Opaque, stable object reference. Use the slug returned by the API.
• page · integer
• page_size · integer — Default 20, max 50.

Drop one entry from the workspace shortlist.

• shortlist_id · string · required — Opaque, stable object reference. Use the slug returned by the API.

SENDS A REAL MESSAGE TO A REAL PERSON, with optional email. One call, one recipient — no bulk parameter and there will not be one. The message is delivered by Aptora from our address; you never receive the candidate's address, and they can reply in Aptora if they want to or switch outreach off entirely. Each accepted message is metered against the workspace’s current plan allowance. Reuse an idempotency_key for retries of the same draft. Ask the user before calling this.

• idempotency_key · string — Stable UUID for this reviewed draft; reuse on retries.
• cv_id · string · required — Opaque, stable object reference. Use the slug returned by the API.
• job_id · string — Opaque, stable object reference. Use the slug returned by the API.
• request_hourly_rate · boolean — Ask for an hourly rate (EUR net plus VAT); default false.
• request_availability · boolean — Ask for start date and hours per week; default false.
• subject · string · required
• body · string · required — Plain text; no HTML.