# Superlink API

The Superlink API is **one agentic endpoint**: *find the best people for X*. You state a
goal; a bounded loop searches a talent graph, evaluates each candidate against a synthesized
scorecard, and returns a ranked, scored shortlist plus a supply report explaining how much of
the market was covered and why it stopped. Search, evaluation, and enrichment are internal
steps of the loop — they are not separate endpoints.

Base URL: https://api.superlink.ai
Auth: every request needs `Authorization: Bearer sl_live_...`.

The API is asynchronous: start a run (202), then poll it until it completes.

## 1. Start a run

`POST /v1/sourcing-runs`

Body (all goal inputs optional, but provide at least one of goal / jobDescription /
jobDescriptionUrl / criteria):

```json
{
  "goal": "the 5 best infra engineers who've scaled distributed training",
  "jobDescription": "optional pasted JD",
  "jobDescriptionUrl": "https://example.com/jd  (optional; fetched + parsed)",
  "hiringManagerNotes": "optional",
  "exemplarLinkedinUrls": ["https://linkedin.com/in/jane-doe"],
  "criteria": { "dimensions": ["optional explicit scorecard dimensions"] },
  "excludeCompany": "https://linkedin.com/company/acme  (optional)",
  "targetCount": 5,
  "minScore": 7,
  "budget": { "maxRounds": 8, "maxFetched": 200, "maxDurationMs": 1800000, "maxCostUsd": 25 }
}
```

`targetCount` is a ceiling and `minScore` (0–10, default 7) is a hard floor — the response
only ever contains candidates scoring at or above `minScore`, so a thin market returns fewer
than `targetCount` (possibly zero). Quality over quantity, by design.

curl:

```bash
curl -X POST https://api.superlink.ai/v1/sourcing-runs \
  -H "Authorization: Bearer sl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"goal":"the 5 best infra engineers who have scaled distributed training","targetCount":5,"minScore":7}'
```

Response (202):

```json
{ "runId": "…", "status": "queued", "poll": "/v1/sourcing-runs/…" }
```

## 2. Poll the run

`GET /v1/sourcing-runs/{id}`

```bash
curl https://api.superlink.ai/v1/sourcing-runs/RUN_ID -H "Authorization: Bearer sl_live_..."
```

While running, `progress` shows the live loop trace; when `status` is `completed`, `result`
holds the shortlist and the supply report:

```json
{
  "id": "…",
  "status": "queued | running | completed | failed",
  "progress": { "round": 2, "phase": "searching", "strongFound": 3, "evaluated": 84, "fetched": 0 },
  "result": {
    "candidates": [
      {
        "score": 8.6,
        "dimensions": [ { "name": "…", "score": 9, "weight": 0.4, "explanation": "…" } ],
        "analysis": "…",
        "enrichment": { "depth": "deep", "step": "index", "version": 1, "outdated": false,
                        "sources": ["linkedin", "github"], "signals": { "builder": true, "availability": false } },
        "profile": { "name": "…", "headline": "…", "photoUrl": "https://api.superlink.ai/v1/img/…", "experience": [], "education": [], "skills": [] }
      }
    ],
    "supplyReport": {
      "rounds": 3, "totalEvaluated": 140, "newProfilesFetched": 0,
      "stoppedReason": "converged", "confidence": "high",
      "gaps": ["staff-level RL infra in EU is thin"]
    }
  },
  "error": null
}
```

Notes:
- `profile` is a canonical, multi-source profile. Every image URL is proxied through
  https://api.superlink.ai/v1/img/… (load them directly in an <img>; no auth header needed).
- `enrichment.depth` ("shallow" | "indexed" | "deep") tells you how deeply a profile has been
  enriched.
- `supplyReport.stoppedReason` is one of: `converged`, `budget_exhausted`, `supply_exhausted`.

Full machine-readable spec: https://api.superlink.ai/openapi.json — interactive docs: https://api.superlink.ai/reference