# Agent setup

> How a coding agent starts with Corpo API: get a key, make the first call, connect the MCP server, and read the spec.

Canonical: https://corpoapi.com/agents

Corpo API is a company data API. It verifies companies against official registers. Everything here is generated from the live contract, so the paths, limits and errors match the API.

## Get an API key

Create an account at https://app.corpoapi.com and copy a live key. A live key starts with ck_live_. A test key starts with ck_test_ and returns fixtures that are never billed. Keep the key on your server, never in client code.

## Make the first call

Call search first. It is free, needs no company number, and returns the jurisdiction and company_number you pass to every other endpoint. Send the key in the X-API-Key header. Authorization: Bearer with the same key also works.

## Fetch a profile or verify a company

Use the jurisdiction and company_number from the search result. GET the company profile, or POST a verify with the claims to check. A verify returns verified, partial, mismatch, not_found or ambiguous.

## Connect the MCP server

For an agent that speaks Model Context Protocol, point it at https://mcp.corpoapi.com/mcp (Streamable HTTP). The same key works there, and a tool call bills and rate-limits exactly like the REST call behind it. Listing tools is free.

## Read the docs and the spec

Full reference: https://docs.corpoapi.com/llms-full.md. OpenAPI 3.1: https://docs.corpoapi.com/openapi.json. Agent guide: https://docs.corpoapi.com/agents.md. Prefer these over scraping the HTML.

## Example calls

### Search (free)

```bash
curl "https://api.corpoapi.com/v1/search?q=Klarna&jurisdiction=se&limit=5" \
  -H "X-API-Key: ck_live_..."
```

### Company profile

```bash
curl "https://api.corpoapi.com/v1/companies/se/5567370431" \
  -H "X-API-Key: ck_live_..."
```

### Verify a company

```bash
curl -X POST "https://api.corpoapi.com/v1/verify" \
  -H "X-API-Key: ck_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: verify-5567370431" \
  -d '{"jurisdiction":"se","company_number":"5567370431","expected":{"legal_name":"Klarna Bank AB Aktiebolag"}}'
```

### Coverage (free, no key)

```bash
curl "https://api.corpoapi.com/v1/coverage"
```

## Connect the MCP server

`https://mcp.corpoapi.com/mcp` (Streamable HTTP)

Install snippets:

### Claude Code

```bash
claude mcp add --transport http corpo-api https://mcp.corpoapi.com/mcp \
  --header "Authorization: Bearer ck_live_..."
```

### Cursor or any mcp.json client

```json
{
  "mcpServers": {
    "corpoapi": {
      "url": "https://mcp.corpoapi.com/mcp",
      "headers": { "Authorization": "Bearer ck_live_..." }
    }
  }
}
```

Tools:

- `search_companies (GET /v1/search)`

- `get_company (GET /v1/companies/{jurisdiction}/{company_number})`

- `list_officers (GET /v1/companies/{jurisdiction}/{company_number}/officers)`

- `verify_company (POST /v1/verify)`

- `verify_companies_batch (POST /v1/verify/batch)`

- `check_vat (GET /v1/vat/{vat_number})`

- `list_coverage (GET /v1/coverage)`

- `get_usage (GET /v1/usage)`

The server forwards your key to the API gateway, so auth, rate limits and billing are unchanged. The MCP server card is at https://corpoapi.com/.well-known/mcp/server-card.json.

## Rate limits

| Tier | Per second | Per minute |

| --- | --- | --- |

| Free | 5 | 100 |

| Paying | 50 | 2000 |

- Limits are per key, on a fixed 1-second window and a 1-minute window.

- Exceeding either window returns 429 with a Retry-After header in seconds.

- A batch call counts as one request, however many items it carries.

## Errors

Every error is an RFC 9457 application/problem+json object. Branch on code, never on the message. The full list is at https://docs.corpoapi.com/errors.md

```json
{ "type", "title", "status", "code", "detail", "request_id" }
```

- 400 invalid_parameter

- 401 invalid_api_key

- 402 free_tier_exhausted

- 404 company_not_found

- 409 officers_not_available

- 422 missing_identifier_or_name

- 429 rate_limited (read Retry-After)

## Copy-paste resources

- [Agent guide](https://docs.corpoapi.com/agents.md): auth, endpoints, errors, examples for agents

- [Full reference](https://docs.corpoapi.com/llms-full.md): every endpoint, parameter and example

- [OpenAPI 3.1](https://docs.corpoapi.com/openapi.json): machine-readable contract

- [MCP server card](https://corpoapi.com/.well-known/mcp/server-card.json): server name, transport and auth

- [API catalog](https://corpoapi.com/.well-known/api-catalog): RFC 9727 linkset for this API

- [llms.txt](https://corpoapi.com/llms.txt): index of every page as markdown