Skip to Content
KITHDocs

Kith ATS overview

How to call the Kith ATS GraphQL API: its endpoint, authentication, conventions, error codes and limits, with a worked example.

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

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

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.

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:

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

What exists today

The API is being built domain by domain, and the reference shows what exists. Today it reads:

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

Lists are connections

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

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.

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 a caller can act on carries a code, in the error's extensions.code:

{
  "errors": [
    {
      "message": "…",
      "extensions": { "code": "BAD_PAGE" }
    }
  ]
}
CodeWhat it means
BAD_IDAn 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_CURSORAn after or before that is not a cursor the list returned.
BAD_PAGEA page the API does not serve, such as one of more than 200 rows.
TOO_MANY_VALUESA filter given more values than it takes: 200 at most.
SEARCH_TOO_LONGSearch text longer than a search takes: 200 characters at most.

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

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

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

Its variables:

{
  "first": 2
}

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

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

  • Reference: every query, type, field, argument and enum value, generated from the schema.
  • Schema file: the schema as GraphQL SDL, to download.
  • For agents: this site as Markdown and as one file.

On this page