> ## Documentation Index
> Fetch the complete documentation index at: https://dev.kernel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Kernel API reference

## Base URL

```
https://api.kernel.ai/rest
```

All requests must be sent to this base URL over HTTPS.

## What is entity resolution?

Entity resolution is the reasoning-based process Kernel uses to decide what real-world entity a company record represents. It uses names, websites, addresses, email domains, and other signals — not just a simple name lookup — to match records to a canonical entity in Kernel's database.

Each resolved entity returns a structured identity result with confidence levels, legal and trading information, and entity classification. The process is asynchronous — you submit a company, get back an `id`, and poll for the result.

## What is firmographic enrichment?

Firmographic enrichment adds operational status, location, headcount, and revenue data to a resolved entity. You submit a `kernel_id` from entity resolution and receive structured firmographic data. Like entity resolution, it runs asynchronously.

For the full firmographic result schema, see [Firmographic result](/api-reference/schemas/firmographic-result).

## Authentication

All endpoints are authenticated using an API key in the `x-api-key` header:

```
x-api-key: <your-api-key>
```

Generate and manage API keys from [Settings > API keys](https://app.kernel.ai) in the Kernel app.

<Tip>
  Store your API key in an environment variable and never commit it to source control.

  ```bash theme={null}
  export KERNEL_API_KEY="ker_your_api_key_here"
  ```
</Tip>

## Async workflow

All operations run asynchronously. Each one returns an `id` you poll until the result is ready.

1. **Start** — call [Resolve entity](/api-reference/endpoint/create-entity-resolution) with the company details.
2. **Poll** — call [Get entity resolution result](/api-reference/endpoint/get-entity-resolution) with the `id`. Use exponential backoff between requests (start at 2 seconds, max 30 seconds).
3. **Read result** — when `status` is `completed`, the `record` object is included with the resolved identity. When `status` is `failed`, `record` is `null`.

Jobs transition linearly: `pending` → `processing` → `completed` | `failed`. Terminal states do not change.

## Job types

The API uses a job-based architecture. Each endpoint corresponds to a specific job type that determines how the request is processed. The job type is determined by the endpoint path — you do not specify it explicitly.

| Endpoint                             | Description                         |
| ------------------------------------ | ----------------------------------- |
| `POST /v1/entity-resolution`         | Async entity resolution             |
| `GET /v1/entity-resolution/{job_id}` | Poll entity resolution result       |
| `POST /v1/resolve-parent`            | Async parent hierarchy resolution   |
| `GET /v1/resolve-parent/{job_id}`    | Poll resolve parent result          |
| `POST /v1/firmographics`             | Async firmographic enrichment       |
| `GET /v1/firmographics/{job_id}`     | Poll firmographic enrichment result |

## Data formats

The API uses the following standards for structured fields:

| Data type     | Standard                                          | Example                                           |
| ------------- | ------------------------------------------------- | ------------------------------------------------- |
| Country       | ISO 3166-1 alpha-2 preferred, any format accepted | `US`, `United States`, `United States of America` |
| Date and time | ISO 8601                                          | `2025-05-28T14:30:00Z`                            |
| Confidence    | Enum                                              | `HIGH`, `MEDIUM`, `LOW`                           |

## Errors

The API uses standard HTTP status codes:

| Status | Meaning                                | Action                                     |
| ------ | -------------------------------------- | ------------------------------------------ |
| `403`  | Forbidden — missing or invalid API key | Check your API key                         |
| `429`  | Rate limit exceeded                    | Wait for `Retry-After` seconds, then retry |
| `500`  | Internal server error                  | Retry with exponential backoff             |

## Rate limits

Rate limiting is not currently enforced but will be added in a future update. We recommend building retry logic with exponential backoff and respecting `429` responses and `Retry-After` headers when they are introduced.

## Versioning

The current API version is **v1**. We will give at least 6 months notice before deprecating a version. Breaking changes will always be introduced under a new path prefix (e.g. `/v2/`).

## Related topics

<CardGroup cols={2}>
  <Card title="API keys" icon="key" href="/api-reference/endpoint/api-keys">
    Create and manage API keys for authentication.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/endpoint/webhooks">
    Receive HTTP callbacks when jobs complete or fail.
  </Card>
</CardGroup>