Carerix
Read/write Carerix (recruiting ATS/CRM) via its GraphQL API — list/get candidates, vacancies, companies, contacts, matches and notes; create candidates and notes; update matches. Use when the user mentions Carerix, pushing candidates into the ATS, or reading vacancies/companies. Keys: BYOK-only — the workspace connects a Carerix confidential client (Client ID + secret + tenant name).
Ask for the outcome and your agent composes the run itself. Or start from a skill, a whole pipeline it already knows end to end.
browse all skills →What your agent reads before it touches Carerix
Every tool ships with a written playbook, and the agent loads it before the first call. Auth, rate limits, what each call costs, which actions need your approval, and the mistakes worth avoiding. It is the difference between an agent that knows the tool and one that guesses at it.
Read the Carerix docs →Show the raw playbookwritten for the agent
HOW in lib/carerix.py.
Auth & config (client credentials)
- Endpoint: one GraphQL endpoint,
https://api.carerix.io/graphql/v1/graphql; every call is a fixed, typed document. - Auth: OAuth 2.0 client credentials from a Carerix confidential client. The token URL is built from the tenant name read off the pasted Carerix URL (e.g.
https://acme.carerix.net→acme); the pasted URL is never fetched. Tenants on a non-default identity host are not supported yet. The token is cached until shortly before it expires; an HTTP 401 triggers one fresh-token retry (also after a GraphQLUNAUTHENTICATEDon the top-level field, which means nothing ran). - BYOK:
api_key= Client ID;client_secretandtenantare the extra fields. Permissions are controlled in Carerix, on the client. A connected workspace never reads env. ping()= safe read-only pilot.
Noun mapping
Candidate = CREmployee, Vacancy = CRVacancy, Company = CRCompany, Contact = person at a company, Match = candidate-to-vacancy link carrying the pipeline status, Note = a to-do of kind note.
Operations
Candidates: list_candidates, search_candidates, get_candidate, create_candidate, create_candidates_batch.
Vacancies / companies / contacts: list_vacancies, get_vacancy, list_companies, get_company, list_contacts, get_contact.
Matches / notes: list_matches, get_match, update_match, list_notes, get_note, create_note.
- Filters are Carerix qualifier strings —
list_*/search_candidatestakequalifier. One page per call:pagefrom 0,page_sizemax 100, rejected above that, not clamped. - A GraphQL
errors[]array or a missing result raises even on HTTP 200. - Rate limit 10 req/s = 600/min, paced per client + tenant. Reads retry 429/5xx with backoff; writes are not retried after a timeout or server error (only after a 429 or an authentication refusal (HTTP 401, or GraphQL
UNAUTHENTICATEDon the top-level field), which Carerix rejects before they run). - No delete operation is exposed for any record.
Guardrail
Production ATS writes — pilot one record, confirm, then bulk. Carerix documents no idempotency key for creates, so never blind-retry one. Required fields, the duplicate-detection key and status ids are tenant-specific.
Handoff
ATS write target: enriched candidates → create_candidate.
Callable surface
Call via the CLI: hyreflow tools execute carerix <method> --payload '{...}' (preview with --dry-run; hyreflow tools get carerix <method> returns the live contract + cost). Base: https://api.carerix.io/graphql/v1/graphql. Only the methods listed below are callable.
batch(method: str, calls: list, *, stop_on_error: bool = False) -> dict— Batched get/update/create: run one method over many inputs, rate-limited.create_candidate(payload: dict, *, dedupe: bool = True) -> dict— POST /graphql/v1/graphql — crEmployeeCreate: create a candidate (CREmployeeRequest, e.g. {"firstName", "lastName", "emailAddress"}).create_candidates_batch(payloads: list[dict], *, stop_on_error: bool = False) -> dict— POST /graphql/v1/graphql — crEmployeeCreate: create many candidates sequentially and rate-limited, each with Carerix's duplicate detection on (its match key is tenant-specific: search first).create_note(payload: dict) -> dict— POST /graphql/v1/graphql — crToDoCreate: add a note to a candidate, vacancy, match, company or contact.get_candidate(candidate_id: str) -> dict— POST /graphql/v1/graphql — crEmployee: one candidate by id.get_company(company_id: str) -> dict— POST /graphql/v1/graphql — crCompany: one company by id.get_contact(contact_id: str) -> dict— POST /graphql/v1/graphql — crContact: one contact by id.get_match(match_id: str) -> dict— POST /graphql/v1/graphql — crMatch: one match by id.get_note(note_id: str) -> dict— POST /graphql/v1/graphql — crNote: one note by id.get_vacancy(vacancy_id: str) -> dict— POST /graphql/v1/graphql — crVacancy: one vacancy by id.list_candidates(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict]— POST /graphql/v1/graphql — crEmployeePage: one page of candidates (CREmployee), oldest first.qualifieris Carerix's filter string.list_companies(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict]— POST /graphql/v1/graphql — crCompanyPage: one page of client companies (CRCompany), oldest first.list_contacts(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict]— POST /graphql/v1/graphql — crContactPage: one page of client contacts (CRUser), oldest first.list_matches(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict]— POST /graphql/v1/graphql — crMatchPage: one page of matches (CRMatch), the candidate-to-vacancy links that carry the pipeline status.list_notes(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict]— POST /graphql/v1/graphql — crNotePage: one page of notes (a note is a CRToDo), oldest first.list_vacancies(qualifier: str | None = None, page: int = 0, page_size: int = 100) -> list[dict]— POST /graphql/v1/graphql — crVacancyPage: one page of vacancies (CRVacancy), oldest first.ping() -> dict— POST /graphql/v1/graphql — crEmployeePage: free read, one row count. Verifies the credentials, tenant and candidate read access (the BYOK probe).search_candidates(qualifier: str, page: int = 0, page_size: int = 100) -> list[dict]— POST /graphql/v1/graphql — crEmployeePage: one page of candidates matching a required qualifier, e.g.emailAddress = '[email protected]'.update_match(match_id: str, payload: dict) -> dict— POST /graphql/v1/graphql — crMatchUpdate: update a match's notes or move its pipeline status.