---
title: "Introduction"
description: "B2B data enrichment API for developers. Look up profiles and companies, and search our data lake by any attribute, all with a single HTTP request."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.kooperativa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

Kooperativa gives you structured B2B data via a single REST API. Look up any person or company, search profiles and companies with filters, and monitor changes with webhooks.

## Base URL

```
https://kooperativa.io/api/v1
```

:::note
All requests must be made over HTTPS. HTTP requests will be rejected.
:::

## Authentication

Every request requires an API key passed as a Bearer token:

```http
Authorization: Bearer ik_live_...
```

Generate keys from your [dashboard](https://kooperativa.io/api-keys). Keys start with `ik_live_`.

:::tip
Use environment variables to store your API key. Never hardcode it in source code or commit it to version control.
:::

## Credits

All endpoints cost **1 credit per request**. Credits are only charged on a successful response.

:::note
A `404` / not-found response **never** consumes credits. `/me` and `/health` are always free regardless of response.
:::

Credits **never expire**. They stay in your account until used.

## Data freshness

All data is served from our own data lake, continuously refreshed in the background. Every record exposes a `fetched_at` timestamp so you can tell how recent it is.

## Response format

All responses are JSON. Successful responses wrap data in a `data` key:

```json
{
  "data": { ... }
}
```

Errors return an `error` string with an appropriate HTTP status code:

```json
{
  "error": "Profile not found"
}
```

## Rate limits

Default: **1,200 requests per minute** per API key.

:::tip
If you need higher rate limits for batch processing, contact [support@kooperativa.io](mailto:support@kooperativa.io) to increase limits for your workspace.
:::

## Credit limit errors

If your workspace owner has set a personal credit limit for your account and you exceed it, you'll receive:

```json
{
  "error": "Credit limit reached. You have used your allocated credits for this month. Please contact your workspace owner to increase your limit."
}
```

:::caution
This is different from the workspace running out of credits. Your workspace owner can adjust per-user limits from the Team settings page.
:::

## Quick start

```bash title="1. Check the API is up"
curl https://kooperativa.io/api/v1/health
```

```bash title="2. Enrich your first person"
curl "https://kooperativa.io/api/v1/person?username=satyanadella" \
  -H "Authorization: Bearer ik_live_..."
```

```bash title="3. Check your credit balance"
curl https://kooperativa.io/api/v1/me \
  -H "Authorization: Bearer ik_live_..."
```

Source: https://docs.kooperativa.io/introduction/index.mdx