> ## 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.

# SDK

> The TypeScript client for the Agentic ID API, and how to call the API directly until the client is published.

> [!WARNING]
>
> The TypeScript SDK is not on npm yet. Its package, `@ic/agentic-id-sdk` (version 0.1.0), is private. Until it is published, call the REST API directly. The API reference lists every endpoint: [API reference](https://docs-agentic-id.icustomer.ai/api-reference/introduction.md).

## Call the API without the SDK

Any HTTP client works. Send your API key as a Bearer token.

```bash curl theme={null}
curl -s https://YOUR_AGENTIC_ID_HOST/v1/resolve \
  -H "Authorization: Bearer ic-live-..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"identifiers":{"company_domain":"acme.example"},"max_credits":1}'
```

```ts TypeScript (fetch) theme={null}
const res = await fetch('https://YOUR_AGENTIC_ID_HOST/v1/resolve', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.AGENTIC_ID_API_KEY}`,
    'content-type': 'application/json',
    'idempotency-key': crypto.randomUUID(),
  },
  body: JSON.stringify({ identifiers: { company_domain: 'acme.example' }, max_credits: 1 }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.status} ${body.code}: ${body.detail}`);
console.log(body.id, body.outcome, body.cost);
```

## What the SDK is

A typed client with one method per product. Request and reply types come from the same schemas the API validates with.

### Create a client

```ts theme={null}
import { AgenticId } from '@ic/agentic-id-sdk';

const aid = new AgenticId({
  apiKey: process.env.AGENTIC_ID_API_KEY,
  baseUrl: 'https://YOUR_AGENTIC_ID_HOST',
});
```

**apiKey** `string`

Your API key. Falls back to the `AGENTIC_ID_API_KEY` environment variable. The constructor throws when neither is set.

**baseUrl** `string`

The API address. Falls back to the `AGENTIC_ID_URL` environment variable, then to a local address. Set it.

**timeoutMs** `number` (default: 300000)

Per call, in milliseconds. Discover can take minutes.

**fetch** `function`

A `fetch` implementation to use in place of the global one.

### One call per product

```ts theme={null}
// Is this mailbox real?
await aid.validate({ emails: ['alex.rivera@acme.example'], max_credits: 1 });

// One stable Agentic ID for a person or company
const { id } = await aid.resolve({ identifiers: { company_domain: 'acme.example' } });

// Fill in missing facts, each with its level and source
await aid.enrich({ contact: { email: 'alex.rivera@acme.example' }, fields: ['title'], max_credits: 2 });

// People in a role inside one company
await aid.find({ account: { domain: 'acme.example' }, roles: ['VP Marketing'], limit: 2, max_credits: 4 });

// Companies that match filters. count_only is not charged.
await aid.discover({ account_filters: { industry: ['software'], country: ['GB'] }, count_only: true });

// Companies like your seeds
await aid.lookalike({ seeds: ['acme.example', 'globex.example'], max_accounts: 10, max_credits: 10 });

// One ID's ledger, re-checked
await aid.ledger(id);

// Each fact's level and the evidence behind it
await aid.facts(id);

// Which workspace and scopes this key has
await aid.me();
```

| Method | Endpoint |
| - | - |
| `validate(body)` | `POST /v1/validate` |
| `resolve(body)` | `POST /v1/resolve` |
| `enrich(body)` | `POST /v1/enrich` |
| `find(body)` | `POST /v1/find` |
| `discover(body)` | `POST /v1/discover` |
| `lookalike(body)` | `POST /v1/lookalike` |
| `ledger(id)` | `GET /v1/ledger/{id}` |
| `facts(id)` | `GET /v1/facts/{id}` |
| `me()` | `GET /v1/me` |

Not in the SDK today: `GET /v1/workspace`, `GET /v1/credits` and `POST /v1/feedback`. The SDK does not send an `Idempotency-Key` and does not retry. It authenticates with an API key only.

### Errors

A response that is not 2xx throws `AgenticIdError`.

```ts theme={null}
import { AgenticId, AgenticIdError } from '@ic/agentic-id-sdk';

try {
  await aid.enrich({ contact: { email: 'alex.rivera@acme.example' }, max_credits: 2 });
} catch (e) {
  if (e instanceof AgenticIdError) {
    console.error(e.status, e.code, e.detail);
    console.error(e.problem.request_id);
  }
}
```

| Property | Type | Meaning |
| - | - | - |
| `status` | number | HTTP status |
| `code` | string or undefined | The stable error code, for example `credits.insufficient` |
| `detail` | string | What went wrong, in plain words |
| `problem` | object | The full problem body the API sent |

A network failure or a timeout throws the underlying `fetch` error, not `AgenticIdError`.

Codes and what to do: [Errors](https://docs-agentic-id.icustomer.ai/errors.md).


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