# Kith ATS overview (/ats)

Kith ATS is the applicant tracking system. Its API is one GraphQL schema, written out type by type, with a description on every type, field, argument and enum value.

## Endpoint [#endpoint]

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

This address will move to `https://ats.kith.contact/graphql`. The schema and everything else on this page stay as they are; only the address changes.

One endpoint serves the whole API.

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

A request is a JSON body sent over POST. The body holds the GraphQL document as `query` and, when the document takes any, its `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 was asked for under `data`:

```json
{
  "data": {
    "viewer": {
      "workspace": {
        "id": "<workspace id>",
        "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.
- Any member can make their own keys in the app's Settings.
- The [`viewer`](/ats/reference/queries/viewer) query says who is making a request: use it to check which workspace a key belongs to.

## What exists today [#what-exists-today]

The API is being built domain by domain, and the [reference](/ats/reference) shows what exists. Today it reads:

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

There are no mutations yet, and most domains are still to come. An operation that is not in the reference does not exist yet.

## Conventions [#conventions]

### Lists are connections [#lists]

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

- Ask for a page with `first`, and for the page after a cursor with `after`. A page holds 50 rows when `first` is left out, and 200 at most.
- A page's rows are its `edges`, each a `node` with its `cursor`. Its [`pageInfo`](/ats/reference/objects/page-info) says whether more follows.
- To read on, pass `pageInfo.endCursor` as `after`, for as long as `pageInfo.hasNextPage` is true.
- `last` and `before` read back from the end of a list in the same way.
- A list is in id order unless its field says otherwise.

### Ids [#ids]

An id is the record's own: the one in the record's 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`](/ats/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`](/ats/reference/scalars/date-time) scalar.

## Errors [#errors]

An error a caller can act on carries a code, in the error's `extensions.code`:

```json
{
  "errors": [
    {
      "message": "…",
      "extensions": { "code": "BAD_PAGE" }
    }
  ]
}
```

| Code | What it means |
| --- | --- |
| `BAD_ID` | An id that is not in the form the API's ids take. 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 does not serve, such as one of more than 200 rows. |
| `TOO_MANY_VALUES` | A filter given more values than it takes: 200 at most. |
| `SEARCH_TOO_LONG` | Search text longer than a search takes: 200 characters at most. |

Any other failure is reported as an unexpected error, with no detail.

## Limits [#limits]

- A document holds at most 30 aliases, 5,000 tokens and 20,000 characters. An introspection query is held to the same limits.
- A query is also limited by its depth, its breadth and its cost. A list costs a statement of its own, and multiplies the cost of what is asked for under it by the size of its page. So a list inside a list is cheaper with smaller pages: ask for the `first` rows you need.

## A worked example [#example]

The workspace's open jobs, two at a time, with [`jobs`](/ats/reference/queries/jobs) and its [`JobFilter`](/ats/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
    }
  }
}
```

Its variables:

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

The shape of the answer. The values are examples, and an id or a cursor is shown as a placeholder:

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

`hasNextPage` is true, so there is more: send the same document again with `endCursor` as `after`.

## The schema [#schema]

- [Reference](/ats/reference): every query, type, field, argument and enum value, generated from the schema.
- [Schema file](/schemas/ats.graphql): the schema as GraphQL SDL, to download.
- [For agents](/agents): this site as Markdown and as one file.