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/graphqlOne 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.
viewersays which workspace a key belongs to.
What you can read
- The workspace a key acts in:
viewer. - Jobs:
jobandjobs. - Candidates:
candidateandcandidates. - A candidate's place on a job, with their stage, grade and decision:
jobCandidate, thecandidatesof aJoband thejobsof aCandidate.
Conventions
Lists are connections
Every list is a connection, read a page at a time.
firstsets the page size: 50 when left out, 200 at most. Givefirstorlast, not both.- A page's rows are its
edges, each anodewith itscursor. ItspageInfosays whether more follows. - To read on, pass
pageInfo.endCursorasafterwhilepageInfo.hasNextPageis true. lastandbeforeread 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" }
}
]
}| 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
- 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
firstrows 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.