AI Agent Skill Integration

This guide explains how to give AI agents access to Vitae's candidate matching pipeline. Whether you use Cursor, Claude Projects, ChatGPT, Cline, or any other agent framework, the pattern is the same: store an API key locally, give the agent instructions for calling two endpoints, and let it search your talent pool by job description.

Setup

1. Create an API key

Go to Settings → API Keys → New Key in the Vitae UI. Copy the key — it starts with vtk_ and is only shown once.

2. Store the key locally

Agents that use shell commands (curl, scripts) read the key from a local config file. Create it with secure permissions:

mkdir -p ~/.vitae
echo '{"api_key": "vtk_YOUR_KEY_HERE"}' > ~/.vitae/config.json
chmod 600 ~/.vitae/config.json

3. Add instructions to your agent

Copy the agent instructions from the AI Settings → Agent Skills card and paste them into your agent's context. Where you paste depends on your framework:

• Cursor — .cursor/rules/ or project-level rules
• Claude Projects — Project instructions panel
• ChatGPT — Custom instructions or project knowledge
• Cline / Windsurf — Project-level instructions file

4. Verify

Test that the key works by calling the config endpoint. This is free and doesn't count against your daily quota:

curl -s "https://vitae.build/api/v1/org/settings/matching/skill-config" \
  -H "Authorization: Bearer $(jq -r .api_key ~/.vitae/config.json)" | jq .

A 200 response with your org's matching defaults, tier, and usage means everything is working.

Config endpoint

Returns the organisation's matching defaults, rate limits, and current daily usage. Agents should call this before every match session to get fresh defaults and check remaining quota.

{
  "matching_defaults": {
    "top_n": 10,
    "similarity_threshold": 0.5,
    "auto_filter_requirements": true,
    "include_reasoning": true
  },
  "api_base_url": "https://vitae.build",
  "match_endpoint": "/api/v1/candidates/match",
  "rate_limits": {
    "requests_per_minute": 10,
    "daily_limit": 30
  },
  "usage": {
    "matches_today": 5,
    "daily_limit": 30,
    "remaining_today": 25
  },
  "tier": "professional"
}

Match endpoint

Runs a two-stage search against the organisation's candidate pool: pgvector embedding similarity pre-filter, then optional LLM re-ranking with reasoning. Each call counts against the daily quota.

Request schema

Request examples

curl -s -X POST "https://vitae.build/api/v1/candidates/match" \
  -H "Authorization: Bearer $(jq -r .api_key ~/.vitae/config.json)" \
  -H "Content-Type: application/json" \
  -d '{
    "job_description": "Senior Python Developer with FastAPI and PostgreSQL experience for a SaaS product team.",
    "top_n": 5
  }' | jq .

Response schema

Match candidate fields

{
  "matches": [
    {
      "candidate_id": "ab24c75d-1234-5678-9abc-def012345678",
      "first_name": "Jan",
      "last_name": "Janssens",
      "professional_title": "Senior Cloud Engineer",
      "current_company": "CloudCorp",
      "skills": ["AWS", "Terraform", "Python", "Kubernetes"],
      "candidate_url": "https://vitae.build/app/candidates/ab24c75d-...",
      "similarity_score": 0.87,
      "match_score": 0.92,
      "reasoning": "Strong match: 5+ years AWS experience, Terraform expertise...",
      "profile_names": ["Cloud Engineering", "DevOps"],
      "profile_links": [
        {
          "profile_id": "1111-aaaa-...",
          "profile_name": "Cloud Engineering",
          "profile_url": "https://vitae.build/app/candidates/ab24c75d-...?profile=1111-aaaa-..."
        }
      ]
    }
  ],
  "total_candidates_searched": 47,
  "total_above_threshold": 12,
  "embedding_model": "text-embedding-3-small"
}

Agent workflow

When a user asks an agent to find candidates (e.g., "Find me 5 senior Java developers in Brussels who speak Dutch"), the agent should follow this sequence:

1. Fetch org defaults — call GET /api/v1/org/settings/matching/skill-config. Check usage.remaining_today. If 0, tell the user the daily limit is reached and stop.
2. Build the job description — if the user pastes a full JD, use it as-is. If they describe the role informally, compose a structured JD from their input.
3. Choose parameters — use org defaults from step 1 unless the user specifies different values (e.g., "find 5 candidates" overrides top_n, "only Dutch speakers" adds a language filter).
4. Call the match endpoint — POST /api/v1/candidates/match with the job description, parameters, and any filters.
5. Present results — for each candidate, show name, title, company, key skills, score, and reasoning. Include candidate_url links. Group by match quality if helpful (strong / partial / weak).
6. Offer next steps — suggest adjusting filters, lowering the threshold, viewing full profiles, or searching with different parameters.

Matching pipeline

The match endpoint uses a two-stage pipeline for fast, accurate results:

1. Embedding similarity — the job description is embedded using text-embedding-3-small and compared against candidate embeddings via pgvector cosine similarity. This produces similarity_score.
2. LLM re-ranking — when include_reasoning: true, the top candidates are re-ranked by GPT with a detailed reasoning explanation. This produces match_score and reasoning.

Results are sorted by match_score when reasoning is enabled, otherwise by similarity_score.

Understanding scores

• similarity_score (0.0–1.0) — fast approximate match from pgvector. Always present. Good for quick filtering.
• match_score (0.0–1.0) — nuanced LLM re-ranking score. Present when include_reasoning: true. More accurate but slower.

A similarity_score of 0.7+ usually indicates a strong semantic match. Below 0.4 is typically a weak match. The match_score accounts for nuances the embedding model misses (years of experience, specific certifications, cultural fit signals in the JD).

Filter options

Filters apply hard constraints before similarity scoring. Use them for non-negotiable requirements:

• skills (string[]) — match candidates with at least one of these skills
• languages (string[]) — match candidates who speak at least one of these languages
• country (string) — match candidates in this country
• city (string) — match candidates in this city

Error handling

Rate limits and quotas

• Per-minute: 10 requests/minute
• Daily (Professional): 30 matches/day
• Daily (Enterprise): 500 matches/day

The config endpoint (GET /skill-config) does not count against quotas. Daily limits reset at midnight UTC.

Tips for better results

• Longer JDs produce better matches. A full job description with responsibilities, requirements, and nice-to-haves produces much better semantic matches than "find me a Python developer."
• Start with org defaults. The admin has tuned them for the org. Only override when the user explicitly asks.
• Skip reasoning for speed. Set include_reasoning: false for faster results when you just need a quick list.
• Sparse candidates won't appear. Candidates with less than 50 characters of text content have no embeddings and won't show up in results.
• Matching is org-scoped. You only see candidates belonging to the organisation that owns the API key.

Related pages

• Candidate Matching Overview
• Matching Request & Response
• Matching Errors & Limits
• Authentication & API Keys