Aptly Intelligence
API Reference

X-API-Key: aptly_your_key_here

curl -X POST https://aptly-backend-unk2.onrender.com/api/v1/screen \
  -H "X-API-Key: aptly_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "job_spec": "Senior Python developer with 5+ years FastAPI experience...",
    "candidates": [
      {
        "candidate_ref": "internal-id-001",
        "cv_text": "7 years Python experience, built APIs with FastAPI..."
      }
    ]
  }'

{
  "job_id":              "3f8a2b1c-d4e5-4f67-89ab-cdef01234567",
  "status":            "pending",
  "total_candidates":  1,
  "expires_at":        "2026-04-27T01:40:45.160801"
}

curl https://aptly-backend-unk2.onrender.com/api/v1/jobs/3f8a2b1c-d4e5-4f67-89ab-cdef01234567 \
  -H "X-API-Key: aptly_your_key_here"

https://aptly-backend-unk2.onrender.com

{
  "job_spec": "Senior Python Developer with 5+ years of experience building production APIs. Must have: FastAPI or Django REST, PostgreSQL, experience with async Python. Nice to have: AWS, Docker, Redis.",
  "candidates": [
    {
      "candidate_ref": "ats-candidate-8821",
      "cv_text": "Jane Smith. Software Engineer. 7 years Python experience..."
    },
    {
      "candidate_ref": "ats-candidate-9034",
      "cv_text": "Mark Chen. Backend Developer. 3 years Node.js, 1 year Python..."
    }
  ],
  "webhook_url": "https://yourapp.com/webhooks/aptly"
}

[
  {
    "id":               1,
    "name":             "Production",
    "key_prefix":       "aptly_upMY--sVyRGeuY",
    "revoked":          false,
    "created_at":       "2026-04-24T01:33:11.984978",
    "last_used_at":     "2026-04-24T09:12:44.000000",
    "monthly_cv_count": 142,
    "billing_month":    "2026-04"
  }
]

{
  "id":          2,
  "name":        "Production",
  "key":         "aptly_upMY--sVyRGeuYGScwOWN4yqlzKRDsx3QwpA-ucNUUd-bCL7DuAFDQ",
  "key_prefix":  "aptly_upMY--sVyRGeuY",
  "created_at":  "2026-04-24T01:33:11.984978",
  "warning":     "Store this key securely. It will not be shown again."
}

{
  "job_spec":    "string",             // required — full job description, plain text
  "candidates": [                      // required — 1 to 200 items
    {
      "candidate_ref": "string",  // required — your internal ID, unique per request
      "cv_text":       "string"   // required — plain text CV content
    }
  ],
  "webhook_url": "string | null"     // optional — must be a publicly accessible HTTPS URL
}

{
  "candidate_ref":  "string",    // echoed from your request
  "score":          84,          // integer 0–100
  "verdict":        "Strong shortlist",  // see Verdicts section
  "match_reasons": [
    "7 years Python meets the senior requirement",
    "FastAPI experience directly matches primary stack",
    "Led distributed backend teams — signals seniority"
  ],                              // up to 4 items, evidence-based
  "gaps": [
    "No AWS or cloud infrastructure experience mentioned",
    "No mention of system design at distributed scale"
  ]                               // up to 3 items, specific and actionable
}

{
  "candidate_ref": "ats-candidate-9034",
  "error":          "JSON decode error"
}

{
  "job_id":  "3f8a2b1c-d4e5-4f67-89ab-cdef01234567",
  "status":  "complete",
  "results": [
    {
      "candidate_ref":  "ats-candidate-8821",
      "score":          84,
      "verdict":        "Strong shortlist",
      "match_reasons":  ["..."],
      "gaps":           ["..."]
    }
  ],
  "failed": []
}

{
  "detail": "Duplicate candidate_ref values found — all candidate_ref values must be unique within a request"
}

import requests
import time

API_BASE = "https://aptly-backend-unk2.onrender.com"
API_KEY  = "aptly_your_key_here"

HEADERS = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

# 1. Submit the screening job
payload = {
    "job_spec": "Senior Python Developer, 5+ years FastAPI...",
    "candidates": [
        {"candidate_ref": "cand-001", "cv_text": "7 years Python, FastAPI, PostgreSQL..."},
        {"candidate_ref": "cand-002", "cv_text": "3 years Node.js, some Python exposure..."},
    ]
}

response = requests.post(f"{API_BASE}/api/v1/screen", json=payload, headers=HEADERS)
response.raise_for_status()
job_id = response.json()["job_id"]
print(f"Job submitted: {job_id}")

# 2. Poll until complete
while True:
    time.sleep(5)
    result = requests.get(
        f"{API_BASE}/api/v1/jobs/{job_id}",
        headers=HEADERS
    ).json()

    if result["status"] == "complete":
        for candidate in result["results"]:
            print(
                f"{candidate['candidate_ref']}: "
                f"{candidate['score']}% — {candidate['verdict']}"
            )
        break
    elif result["status"] == "failed":
        print("Job failed")
        break
    else:
        print(f"Status: {result['status']} — {result['processed_candidates']}/{result['total_candidates']}")

const API_BASE = "https://aptly-backend-unk2.onrender.com";
const API_KEY  = "aptly_your_key_here";

const headers = {
  "X-API-Key":      API_KEY,
  "Content-Type": "application/json"
};

async function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function screenCandidates() {
  // 1. Submit
  const submit = await fetch(`${API_BASE}/api/v1/screen`, {
    method:  "POST",
    headers,
    body: JSON.stringify({
      job_spec:   "Senior Python Developer, FastAPI, 5+ years...",
      candidates: [
        { candidate_ref: "cand-001", cv_text: "7 years Python, FastAPI..." },
        { candidate_ref: "cand-002", cv_text: "3 years Node.js, some Python..." }
      ]
    })
  });

  const { job_id } = await submit.json();
  console.log(`Job submitted: ${job_id}`);

  // 2. Poll
  while (true) {
    await sleep(5000);
    const res = await fetch(`${API_BASE}/api/v1/jobs/${job_id}`, { headers });
    const data = await res.json();

    if (data.status === "complete") {
      data.results.forEach(c =>
        console.log(`${c.candidate_ref}: ${c.score}% — ${c.verdict}`)
      );
      break;
    } else if (data.status === "failed") {
      console.error("Job failed"); break;
    }
    console.log(`Processing: ${data.processed_candidates}/${data.total_candidates}`);
  }
}

screenCandidates();

# Create payload.json first, then:
curl -X POST https://aptly-backend-unk2.onrender.com/api/v1/screen \
  -H "X-API-Key: aptly_your_key_here" \
  -H "Content-Type: application/json" \
  -d "@payload.json"

curl https://aptly-backend-unk2.onrender.com/api/v1/jobs/YOUR_JOB_ID \
  -H "X-API-Key: aptly_your_key_here"

curl https://aptly-backend-unk2.onrender.com/api/v1/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"