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 · integer · required — The CV id.

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 new CV from a COMPLETE AptoraCV resume document. Preserve every field and array entry from your source — do not drop or empty populated sections. Call `get_cv_schema` for the full schema and `validate_cv` for a dry-run first. Common non-AptoraCV wording is normalized automatically (see `normalize`); pass strict=true to have the write rejected instead of losing anything. A field AptoraCV does not have is rejected outright, naming the field to use instead. IDENTITY: in a PERSONAL workspace a profile is always about the signed-in user, so firstName/lastName/name are replaced with the account's own name and the candidate name you send is discarded. That is intended and is NOT data loss — everything else is stored as sent, and the response reports the change under `normalized` with rule `personal_workspace_identity`. To keep someone else's name, import into a TEAM workspace.

• data · object · required — The COMPLETE AptoraCV resume document. When importing an existing CV, preserve every field and every array entry from the source — never replace a populated section (employment.history, projects, education.history, …) with an empty array or omit it. The response echoes how many entries were stored per section so you can verify nothing was lost. The properties below are an outline: every section is named, but only one level deep. Call `get_cv_schema` for the exact types, enums and nested fields, and `validate_cv` to dry-run a document before writing it.
• strict · boolean — Reject the whole import (writing nothing) if any section arrived with more entries than were stored. Default false: the import proceeds and the response reports the difference. A field that is not part of AptoraCV is always rejected, strict or not.
• normalize · boolean — Map common resume wording onto AptoraCV before validating — section aliases (awards→recognition, work→employment), field aliases (startDate→start, awarder→from) and enum values ("master"→"Expert", "Master's Degree"→"degree"). Default true; the response lists every change under `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 — The COMPLETE AptoraCV resume document. When importing an existing CV, preserve every field and every array entry from the source — never replace a populated section (employment.history, projects, education.history, …) with an empty array or omit it. The response echoes how many entries were stored per section so you can verify nothing was lost. The properties below are an outline: every section is named, but only one level deep. Call `get_cv_schema` for the exact types, enums and nested fields, and `validate_cv` to dry-run a document before writing it.
• strict · boolean — Reject the whole import (writing nothing) if any section arrived with more entries than were stored. Default false: the import proceeds and the response reports the difference. A field that is not part of AptoraCV is always rejected, strict or not.
• normalize · boolean — Map common resume wording onto AptoraCV before validating — section aliases (awards→recognition, work→employment), field aliases (startDate→start, awarder→from) and enum values ("master"→"Expert", "Master's Degree"→"degree"). Default true; the response lists every change under `normalized`.
• cv_id · integer · required — The CV id.
• 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 — The COMPLETE AptoraCV resume document. When importing an existing CV, preserve every field and every array entry from the source — never replace a populated section (employment.history, projects, education.history, …) with an empty array or omit it. The response echoes how many entries were stored per section so you can verify nothing was lost. The properties below are an outline: every section is named, but only one level deep. Call `get_cv_schema` for the exact types, enums and nested fields, and `validate_cv` to dry-run a document before writing it.
• strict · boolean — Reject the whole import (writing nothing) if any section arrived with more entries than were stored. Default false: the import proceeds and the response reports the difference. A field that is not part of AptoraCV is always rejected, strict or not.
• normalize · boolean — Map common resume wording onto AptoraCV before validating — section aliases (awards→recognition, work→employment), field aliases (startDate→start, awarder→from) and enum values ("master"→"Expert", "Master's Degree"→"degree"). Default true; the response lists every change under `normalized`.

Delete (soft-delete) a CV by id.

• cv_id · integer · required — The CV id.

List job listings from the Aptora job board that require at least one of the given skills, the listings requiring most of them first and the newer one within an equal count. `skills` is mandatory and needs at least 3 skill ids: the board is searched, never listed whole. Skill ids come from get_cv (`profile_skills`) or from any listing's `required_skills`; an id that names no active skill is refused by name. Every summary carries the listing's `required_skills`, so one call answers which listings fit and why: the result is a board the user pages and opens each listing in, so do not walk the rows with get_job. A bare skill search is served up to page 10; further pages need a narrowing filter (type, title, company or location). Pages and listings of other workspaces are subject to a fair-use read budget: a refusal carries `retry_after` in seconds. Fair use is what the terms of service set out in § 17.

• skills · array<integer> · required — Skill ids to filter by, at least 3. A listing matches when it requires any of them.
• 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 — The job id from list_jobs.

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 — The job id from list_jobs.
• cv_id · integer · required — The CV to apply with.
• 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 user'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. Needs a PERSONAL workspace, exactly like apply_to_job.

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 job listing: reports what is missing or would be ignored, and writes NOTHING. Use it before create_job to avoid half-finished listings. Available on every plan, including plans that cannot create listings; detect_skills is the one part that is not.

• 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
• contact_email · string
• contact_person · string
• expires_at · string — ISO datetime; defaults to the configured window.
• detect_skills · boolean — Also report which skills this job_spec would be matched on — the property that decides whether the listing finds anyone. Runs the detector, so it needs a plan that includes job skill detection; without one the rest of the validation still answers. Off by default.

Create a job listing owned by this workspace. It starts PRIVATE: off the public board and out of candidate matching until publish_job is called on it. Requires a team workspace and nothing else — posting is free on every team plan. Skill detection on the saved spec runs 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
• contact_email · string
• contact_person · string
• expires_at · string — ISO datetime; defaults to the configured window.

Update fields of one of this workspace's job listings. Only the fields you name change; pass null to clear one. Saving never re-runs the skill detection; after a spec change pass detect_skills=true to re-detect — otherwise the listing keeps its previously detected skills.

• job_id · string · required
• 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
• contact_email · string | null
• contact_person · string | null
• detect_skills · boolean — Also re-detect which skills the saved spec is matched on — the property that decides whether the listing finds anyone. Runs the detector, so it spends one detection run and needs a plan that includes job skill detection. 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
• 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

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

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 and job-title fit 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 — One of this workspace's jobs.
• filters · object
• force · boolean — Re-run instead of reusing.

Have a model judge the candidates a finished search found: 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 assessment 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 — A completed search run.
• focus · string — Optional. What to weigh beyond the listing itself.
• force · boolean — Re-assess 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 assessment and is null until refine_search is called. Results are complete and ranked either way — a failed assessment leaves them untouched. Paging costs no allowance.

• run_id · string · required
• 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 · integer · required
• job_id · string
• note · string

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

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

Drop one entry from the workspace shortlist.

• shortlist_id · integer · required

SENDS A REAL EMAIL TO A REAL PERSON. One call, one recipient — there is 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 directly if they want to. A candidate may be contacted by this workspace at most once every 30 days, and may switch outreach off entirely. Ask the user before calling this.

• cv_id · integer · required
• job_id · string — The role this is about.
• subject · string · required
• body · string · required — Plain text; no HTML.