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

# Introduction

> Base URL, authentication, endpoints, request IDs and the error format of the Agentic ID API.

The Agentic ID API is a JSON API over HTTPS. Requests and replies use `snake_case` field names. The endpoint pages in this section are generated from the OpenAPI document.

## Base URL

```text theme={null}
https://YOUR_AGENTIC_ID_HOST
```

All endpoints are under `/v1`.

## Authentication

Send your credential on every request, in either header:

```bash theme={null}
Authorization: Bearer ic-live-...
```

```bash theme={null}
x-api-key: ic-live-...
```

The credential is an API key, or the access token you get when you sign in (OAuth 2.1 with PKCE), sent as a `Bearer` token. See [Authentication](https://docs-agentic-id.icustomer.ai/authentication.md) and [API keys](https://docs-agentic-id.icustomer.ai/api-keys.md).

A request without a valid credential gets `401` with code `auth.invalid_key`. An expired sign-in gets `401` with code `auth.token_expired`.

## Content type

Send `Content-Type: application/json` with a JSON body on every `POST`. Successful replies are `application/json`. Errors are `application/problem+json`.

## Endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/v1/validate` | Is this mailbox real? See [Validate](https://docs-agentic-id.icustomer.ai/products/validate.md). |
| `POST` | `/v1/resolve` | One stable Agentic ID for a person or company. See [Resolve](https://docs-agentic-id.icustomer.ai/products/resolve.md). |
| `POST` | `/v1/enrich` | Fill in the missing facts, each with its level and source. See [Enrich](https://docs-agentic-id.icustomer.ai/products/enrich.md). |
| `POST` | `/v1/find` | People in a role inside one company. See [Find](https://docs-agentic-id.icustomer.ai/products/find.md). |
| `POST` | `/v1/discover` | New companies, and people, that match your filters. See [Discover](https://docs-agentic-id.icustomer.ai/products/discover.md). |
| `POST` | `/v1/lookalike` | Companies like the ones you already have. See [Lookalike](https://docs-agentic-id.icustomer.ai/products/lookalike.md). |
| `POST` | `/v1/feedback` | What happened after you used a value. See [Feedback](https://docs-agentic-id.icustomer.ai/products/feedback.md). |
| `GET` | `/v1/workspace` | The calling workspace: who it is, what it can spend, how it shares. |
| `GET` | `/v1/credits` | Balance, spend by tool, and the latest grants and charges. Takes `limit` (0 to 200, default 20). |
| `GET` | `/v1/facts/{id}` | Every fact's level and evidence for one ID. |
| `GET` | `/v1/ledger/{id}` | One ID's ledger, re-checked. |
| `GET` | `/v1/openapi.json` | The OpenAPI document. |

Every `POST` endpoint returns `200` on success.

## Request IDs

Every response carries an `X-Request-Id` header, including errors. The same value is in the body as `request_id` on every `POST` reply and every error.

```text theme={null}
X-Request-Id: req_5d0c1b9e-2f4a-4a7b-8c3d-6e1f0a9b7c21
```

Log it with each call and quote it when you ask for help.

## Errors

Errors follow RFC 9457 problem details, with content type `application/problem+json`.

```json theme={null}
{
  "type": "https://docs.agentic-id.icustomer.ai/errors/request.invalid",
  "title": "Bad request",
  "status": 400,
  "code": "request.invalid",
  "detail": "The request body does not match the schema.",
  "issues": [
    { "path": "max_credits", "message": "Invalid input: expected number, received undefined" }
  ],
  "request_id": "req_5d0c1b9e-2f4a-4a7b-8c3d-6e1f0a9b7c21"
}
```

| Field | Type | Meaning |
| - | - | - |
| `type` | string | A URL that identifies the error. |
| `title` | string | A short name for the status, for example `Bad request`. |
| `status` | number | The HTTP status. |
| `code` | string | A stable code to branch on, for example `credits.insufficient`. |
| `detail` | string | A plain sentence saying what went wrong and what to do. |
| `request_id` | string | The ID of the call. |

Some errors add fields:

| Field | On | Meaning |
| - | - | - |
| `issues` | `request.invalid` | Each schema problem, with `path` and `message`. |
| `retryAfterSeconds` | `429`, `409 idempotency.in_progress`, `503` | Seconds to wait. The same value is in the `Retry-After` header. |
| `available` | `credits.insufficient` | Credits available to a new call. |
| `rejected` | Unreadable-filter errors on Find and Discover | The filter values that could not be read. |

Branch on `code`, not on `detail`. See [Errors](https://docs-agentic-id.icustomer.ai/errors.md) for every code.

## Idempotency

Send an `Idempotency-Key` header (8 to 200 printable characters, no spaces) on any `POST`. The same key with the same body within 24 hours returns the first answer and is charged once.

A replayed answer carries `Idempotent-Replayed: true`. See [Idempotency](https://docs-agentic-id.icustomer.ai/idempotency.md).

## OpenAPI document

The OpenAPI 3.1 document is served at:

```bash theme={null}
curl https://YOUR_AGENTIC_ID_HOST/v1/openapi.json
```

It needs no credential. It is generated from the same schemas the endpoints check requests with.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.