# Resolve an id or URL to a target (/api/resolve/resolve-target)

`POST /api/resolve`

Polymorphic ID resolution: given a parsed descriptor (run/job/attempt id, a runner id, a bare id, or a GitHub Actions URL), resolve it against the CI facts store to the most specific target, or return a candidate list on ambiguity. A runner id resolves to the job/attempt target(s) that ran on that runner — or, with target=run, to the distinct run(s) it touched; several candidates when a runner is reused. Authenticated; scoped to the caller's orgs by membership.

Base URL: `https://runners.starsling.dev`

## Authentication

Requires a bearer token (`Authorization: Bearer`).

## Request body

Required, sent as `application/json`, `application/x-www-form-urlencoded`, `multipart/form-data`.

- `input` — object, required
  - **Variant 1** — object
    - `kind` — string, required. `run`
    - `github_run_id` — string, required. e.g. `1234567890`
  - **Variant 2** — object
    - `kind` — string, required. `job`
    - `github_job_id` — string, required. e.g. `9876543210`
  - **Variant 3** — object
    - `kind` — string, required. `attempt`
    - `github_job_id` — string, required
    - `attempt` — string | integer, required. 1–4294967295
  - **Variant 4** — object
    - `kind` — string, required. `run_attempt`
    - `github_run_id` — string, required
    - `attempt` — string | integer, required. 1–4294967295
  - **Variant 5** — object
    - `kind` — string, required. `bare`
    - `github_id` — string, required
  - **Variant 6** — object
    - `kind` — string, required. `runner`
    - `github_runner_id` — string, required. e.g. `611593`
- `target` — string. `run`, `job`, `attempt`

## Responses

| Status | Description |
| --- | --- |
| `200` | Either the one target the id resolves to, or the candidates it could mean. Ambiguity is a 200, not an error. |
| `401` | No credential was sent, or the one sent is expired or revoked. Sign in with `sling login`. |
| `404` | No such id in any org you belong to. Deliberately the same answer as an id that exists elsewhere — this never confirms another org's runs. |
| `422` | The request body failed schema validation — `input` is missing or not a recognised descriptor. |
| `500` | The request was valid; the control plane or a dependency it calls failed. |

### `200` body

- **Variant 1** — object
  - `resolved` — object, required
    - **Variant 1** — object
    - **Variant 2** — object
    - **Variant 3** — object
- **Variant 2** — object
  - `candidates` — array<object>, required
    - array of object

### Example

```json
{
  "resolved": {
    "id": "att_9876543210.2",
    "kind": "attempt",
    "run_id": "1234567890",
    "org": "acme",
    "repo": "acme/api",
    "job_id": "9876543210",
    "attempt": 2,
    "job_name": "typecheck",
    "runner_id": "611593",
    "runner_name": "starsling-n-4f2a1c"
  }
}
```