# Kith Sourcing overview (/sourcing)

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 [#endpoint]

```text
https://api.kith.contact/v1/graphql
```

This 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 [#authentication]

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 [#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`:

```json
{
  "query": "{ viewer { workspace { searchAllowance defaultSearchDepth } } }"
}
```

The answer is JSON, with what was asked for under `data`:

```json
{
  "data": {
    "viewer": {
      "workspace": {
        "searchAllowance": "AVAILABLE",
        "defaultSearchDepth": "THOROUGH"
      }
    }
  }
}
```

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

The API is being built one family at a time, and the [reference](/sourcing/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`](/sourcing/reference/queries/viewer);
- the workspace's searches, as a list: [`searches`](/sourcing/reference/queries/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 [#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`](/sourcing/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.
- Each list says what order it is in. [`searches`](/sourcing/reference/queries/searches) is by latest message, newest first.

### Ids [#ids]

An id is the record's own. A search's id is the one in its URL in the app.

### Enums [#enums]

Enum values are upper case, such as `SOURCING`.

### Times [#times]

A time is an ISO 8601 string in UTC, such as `2026-11-16T09:30:00.000Z`: the [`DateTime`](/sourcing/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_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 [#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 `first` rows you need.

## A worked example [#example]

The workspace's searches that mention London, two at a time, with [`searches`](/sourcing/reference/queries/searches).

The document:

```graphql
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:

```json
{
  "first": 2,
  "query": "London"
}
```

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

```json
{
  "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 [#schema]

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