Kith Sourcing overview
How the Kith Sourcing GraphQL API works: its endpoint, who it answers, conventions, error codes and limits, with a worked example.
Kith Sourcing finds people for a role, in a conversation: a search holds its brief, the people Kith found and the decisions on them. 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.kith.contact/v1/graphqlThis address will move to https://sourcing.kith.contact/graphql. The schema and everything else on this page stay as they are; only the address changes.
Who it answers
This is the API Kith's own app is moving onto, and it answers a signed-in member of a workspace. Everything it returns belongs to the workspace that member acts in.
From outside Kith's app, Kith Sourcing is reached today through the Claude connector and through the ATS integration. This API does not take their credentials: a request with an ATS connection's token or the connector's token is refused with the FORBIDDEN error code.
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:
{
"query": "{ viewer { workspace { searchAllowance defaultSearchDepth } } }"
}The answer is JSON, with what was asked for under data:
{
"data": {
"viewer": {
"workspace": {
"searchAllowance": "AVAILABLE",
"defaultSearchDepth": "THOROUGH"
}
}
}
}What exists today
The API is being built one family at a time, and the reference shows what exists. Today it reads:
- the workspace a member acts in, with whether it can start sourcing and its default search depth:
viewer; - the workspace's searches, as a list:
searches.
There are no mutations yet, and most families 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 withafter. A page holds 50 rows whenfirstis left out, and 200 at most. - A page's rows are its
edges, each anodewith itscursor. ItspageInfosays whether more follows. - To read on, pass
pageInfo.endCursorasafter, for as long aspageInfo.hasNextPageis true. lastandbeforeread back from the end of a list in the same way.- Each list says what order it is in.
searchesis by latest message, newest first.
Ids
An id is the record's own. A search's id is the one in its URL in the app.
Enums
Enum values are upper case, such as SOURCING.
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" }
}
]
}| Code | What it means |
|---|---|
BAD_PAGE | A page the API does not serve, such as one of more than 200 rows. |
BAD_CURSOR | An after or before that is not a cursor the list returned. |
SEARCH_TOO_LONG | Search text longer than a search takes: 200 characters at most. |
FORBIDDEN | The request's credential is not one this API answers, such as an ATS connection's token or the connector's. |
An error with a code is an answer like any other. Any other failure is reported as an unexpected error, with no detail: the request is answered with HTTP status 500 and no data.
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 read of its own, and multiplies the cost of what is asked for under it by the size of its page. So ask for the
firstrows you need.
A worked example
The workspace's searches that mention London, two at a time, with searches.
The document:
query Searches($first: Int, $after: String, $query: String) {
searches(first: $first, after: $after, query: $query) {
edges {
cursor
node {
id
title
company
location
status
candidateCount
peopleToReview
lastMessageAt
}
}
pageInfo {
hasNextPage
endCursor
}
}
}Its variables:
{
"first": 2,
"query": "London"
}The shape of the answer. The values are examples, and an id or a cursor is shown as a placeholder:
{
"data": {
"searches": {
"edges": [
{
"cursor": "<cursor of this row>",
"node": {
"id": "<search id>",
"title": "Head of Sales · Example Labs",
"company": "Example Labs",
"location": "London",
"status": "REVIEW",
"candidateCount": 12,
"peopleToReview": 3,
"lastMessageAt": "2026-11-16T09:30:00.000Z"
}
},
{
"cursor": "<cursor of this row>",
"node": {
"id": "<search id>",
"title": "Founding Account Executive · Sample Analytics",
"company": "Sample Analytics",
"location": "London",
"status": "SOURCING",
"candidateCount": 0,
"peopleToReview": 0,
"lastMessageAt": "2026-11-15T16:05:00.000Z"
}
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": "<cursor of the last row>"
}
}
}
}hasNextPage is false, so this page is the last. When it is true, 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.