# Overview (/api)



The StarSling control plane exposes an HTTP API for everything the platform knows about your CI: which runs and jobs executed, why one failed, where the wall-clock went, and what it all cost.

<ApiRequest path="/api/runs?org=acme&limit=5" />

<Callout type="info">
  Prefer a terminal to an HTTP client? The `sling` CLI wraps these same endpoints, adding argument validation, readable tables, and a stable exit-code contract.
</Callout>

## Base URL

All endpoints are served from a single origin:

<ApiBaseUrl />

Every path in this reference is relative to it, and every path is prefixed with `/api`.

## Conventions

Two things hold across every endpoint:

* **Org scoping.** Results are scoped to the orgs you belong to. Org-scoped endpoints take `org` as a **required** parameter (and often an optional `repo`); a resource in an org you cannot see returns `404`, not `403`, so the API never confirms that an id exists elsewhere.
* **Money and time.** Costs are US dollars in `*_usd` fields. Durations are seconds unless the field name says otherwise, and runner minutes are *billed* minutes, `max(1, ceil(duration / 60s))` per job, so a five-second job still costs a minute.

## Endpoint groups

<Cards>
  <Card title="Runs and jobs" href="/api/runs/list-runs" description="List and inspect workflow runs, jobs, and their attempts." />

  <Card title="Logs" href="/api/logs/get-logs" description="Read job log lines, filtered server-side so you fetch only what matters." />

  <Card title="Diagnostics" href="/api/why" description="Deterministic classification of why a job failed, with evidence." />

  <Card title="Timing" href="/api/time/get-time" description="Decompose CI wall-clock into runner-lifecycle phases." />

  <Card title="Usage and billing" href="/api/usage/get-usage" description="Attribute runner minutes and cost; read billing snapshots and invoices." />

  <Card title="Identity" href="/api/identity/get-whoami" description="Confirm who you are authenticated as and which orgs you can reach." />
</Cards>

## Before you start

Two pages cover the behaviour shared by every endpoint. Reading them first saves working it out one `400` at a time:

<Cards>
  <Card title="Authentication" href="/api/credentials" description="Bearer tokens and the scopes each endpoint requires." />

  <Card title="Errors" href="/api/errors" description="The error body shape, the status codes, and what each one means." />
</Cards>