New: Kith open-sources its ATS.Read why
Skip to Content

Kith ATS overview

The Kith ATS GraphQL API: endpoint, authentication, conventions, errors and limits.

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 is generated from it, and the schema file is yours to download.

For a worked example with copyable requests, run a job from intake to placement.

Endpoint

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

One endpoint serves the whole API.

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.

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:

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

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 says which workspace a key belongs to.

What you can read

Conventions

Lists are connections

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 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

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.

Enums

Enum values are upper case, such as LONGLIST.

Times

A time is an ISO 8601 string in UTC, such as 2026-11-16T09:30:00.000Z: the DateTime scalar.

Errors

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

{
  "errors": [
    {
      "message": "A page holds from 1 to 200 rows: 500 was asked for.",
      "extensions": { "code": "BAD_PAGE" }
    }
  ]
}
CodeMeaning
BAD_IDAn id that no record could have. An id that matches no record is not an error: job, candidate and jobCandidate answer null.
BAD_CURSORAn after or before that is not a cursor the list returned.
BAD_PAGEA page the API doesn't serve: fewer than 1 or more than 200 rows, or both first and last.
TOO_MANY_VALUESA filter list with more than 200 values.
SEARCH_TOO_LONGSearch 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

  • 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

The workspace's open jobs, two at a time, with jobs and its JobFilter.

The document:

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:

{
  "first": 2
}

The answer:

{
  "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.