# Kith ATS overview (/api)

The Kith ATS API reads and changes a workspace's jobs and candidates, and each candidate's stage, grade and decision on each job. It is one GraphQL schema: the [reference](/api/reference) is generated from it, and the [schema file](/schemas/ats.graphql) is yours to download.

For a worked example with copyable requests, [run a job from intake to placement](/workflows/headless-ats).

## Endpoint [#endpoint]

```text
https://api.authin.ai/api/graphql
```

One endpoint serves the whole API.

## Making a request [#making-a-request]

POST a JSON body with `Content-Type: application/json`. Put the GraphQL document in `query` and, if it takes variables, they in `variables`.

```bash
curl https://api.authin.ai/api/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: $KITH_ATS_API_KEY" \
  -d '{"query":"{ viewer { workspace { id name slug } } }"}'
```

The answer is JSON, with what you asked for under `data`:

```json
{
  "data": {
    "viewer": {
      "workspace": {
        "id": "42",
        "name": "Example Labs",
        "slug": "example-labs"
      }
    }
  }
}
```

## Authentication [#authentication]

Send an API key in the `x-api-key` header of every request.

- A key belongs to the member who made it and acts as that member, in their workspace. Everything the API returns belongs to that workspace.
- Every member can make keys in the app's Settings, and can delete them there. A deleted key stops working.
- A request with no key, or an unknown one, is answered 401.
- [`viewer`](/api/reference/queries/viewer) says which workspace a key belongs to.

## What you can read [#what-you-can-read]

- The workspace a key acts in: [`viewer`](/api/reference/queries/viewer).
- Jobs: [`job`](/api/reference/queries/job) and [`jobs`](/api/reference/queries/jobs).
- Candidates: [`candidate`](/api/reference/queries/candidate) and [`candidates`](/api/reference/queries/candidates).
- A candidate's place on a job, with their stage, grade and decision: [`jobCandidate`](/api/reference/queries/job-candidate), the `candidates` of a [`Job`](/api/reference/objects/job) and the `jobs` of a [`Candidate`](/api/reference/objects/candidate).

## Conventions [#conventions]

### Lists are connections [#lists]

Every list is a connection, read a page at a time.

- `first` sets the page size: 50 when left out, 200 at most. Give `first` or `last`, not both.
- A page's rows are its `edges`, each a `node` with its `cursor`. Its [`pageInfo`](/api/reference/objects/page-info) says whether more follows.
- To read on, pass `pageInfo.endCursor` as `after` while `pageInfo.hasNextPage` is true.
- `last` and `before` read back from the end of a list.
- Each list's description gives its order.
- A cursor is opaque: pass back the ones you are given.

### Ids [#ids]

An id is the record's own, the one in its URL in the app. A candidate's place on a job has an id of its own, which is not the candidate's id: see [`JobCandidate`](/api/reference/objects/job-candidate).

### Enums [#enums]

Enum values are upper case, such as `LONGLIST`.

### Times [#times]

A time is an ISO 8601 string in UTC, such as `2026-11-16T09:30:00.000Z`: the [`DateTime`](/api/reference/scalars/date-time) scalar.

## Errors [#errors]

An error you can act on carries a code in `extensions.code`:

```json
{
  "errors": [
    {
      "message": "A page holds from 1 to 200 rows: 500 was asked for.",
      "extensions": { "code": "BAD_PAGE" }
    }
  ]
}
```

| Code | Meaning |
| --- | --- |
| `BAD_ID` | An id that no record could have. An id that matches no record is not an error: `job`, `candidate` and `jobCandidate` answer null. |
| `BAD_CURSOR` | An `after` or `before` that is not a cursor the list returned. |
| `BAD_PAGE` | A page the API doesn't serve: fewer than 1 or more than 200 rows, or both `first` and `last`. |
| `TOO_MANY_VALUES` | A filter list with more than 200 values. |
| `SEARCH_TOO_LONG` | Search text longer than 200 characters. |

A failure the API did not expect is answered with HTTP status 500, no `data` and the message `Unexpected error.`

Other statuses: 401 for a missing or unknown key, 405 for any method but POST, 415 for a body that isn't JSON, and 413 for a document or variables over the limits below.

## Limits [#limits]

- A document holds at most 30 aliases, 5,000 tokens and 20,000 characters, and its variables at most 20,000 values. An introspection query has the same limits.
- A query is at most 12 levels deep and costs at most 50,000. A field costs 1. A list costs more, and multiplies the cost of what you ask for under it by the size of its page. A page of 50 jobs, each with a page of 50 candidates, fits. 200 by 200 does not. Ask for the `first` rows you need.

## Example [#example]

The workspace's open jobs, two at a time, with [`jobs`](/api/reference/queries/jobs) and its [`JobFilter`](/api/reference/inputs/job-filter).

The document:

```graphql
query OpenJobs($first: Int, $after: String) {
  jobs(first: $first, after: $after, filter: { statuses: [OPEN] }) {
    edges {
      cursor
      node {
        id
        title
        companyName
        location
        status
        mustHaves
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

The variables:

```json
{
  "first": 2
}
```

The answer:

```json
{
  "data": {
    "jobs": {
      "edges": [
        {
          "cursor": "1204",
          "node": {
            "id": "1204",
            "title": "Founding Account Executive",
            "companyName": "Example Labs",
            "location": "London",
            "status": "OPEN",
            "mustHaves": ["Has closed new business at a seed-stage company"]
          }
        },
        {
          "cursor": "1219",
          "node": {
            "id": "1219",
            "title": "Head of Sales",
            "companyName": "Sample Analytics",
            "location": "Remote",
            "status": "OPEN",
            "mustHaves": []
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "1219"
      }
    }
  }
}
```

`hasNextPage` is true. To read on, send the same document with `endCursor` as `after`.