# Panadata API

> REST API for public registry data in Panama (organizations and natural persons) and Ecuador (organizations only). Search by name or RUC, retrieve detailed records covering corporate governance, assets, trade, legal documents, risk/compliance, and more.

Base URL: `https://api.panadata.net`
Platform: `https://platform.panadata.net`
MCP server: `https://mcp.panadata.net/mcp` (streamable-HTTP — agent-native access, see below)

## Getting started

1. Sign up at https://platform.panadata.net/users/sign_up and confirm your email
2. Create an API key in the dashboard — you'll get a `pk_*` Bearer token
3. Search for an entity, then fetch details with product codes

Free tier: confirmed accounts can query immediately without preloading balance (aggressive rate limits).

## Authentication

All API requests require a Bearer token:

```
Authorization: Bearer pk_XXXXXXXXXXXX
```

## MCP server (for AI agents)

Panadata also exposes this API as a remote **MCP server**, so an AI agent can search and read registry data as native tools instead of hand-built HTTP requests.

- Endpoint: `https://mcp.panadata.net/mcp` (transport: streamable-HTTP)
- Auth: send your `pk_*` key as an `X-Api-Key` header (or `Authorization: Bearer`); the MCP forwards it to the API.
- Billing: tool calls are metered the same way as the REST API (a base charge plus product-code costs) and draw down the same prepaid balance; use `dry_run` to preview a call's cost before spending.

Connect from Claude Code (or any MCP client):

```
claude mcp add --transport http panadata https://mcp.panadata.net/mcp \
  --header "X-Api-Key: pk_XXXXXXXXXXXX"
```

Once connected, the agent resolves an entity by name or RUC, reads its detail with the product codes below, and joins related records itself. Full guide: https://platform.panadata.net/docs/empezar

## Endpoints

### Health check
`GET /health` — No auth required. Returns `{"status":"ok","service":"panadata-api"}`.

### Search entities
`GET /v4/panama/entidades?nombre={name}` — Search Panama by name (min 3 chars).
`GET /v4/panama/entidades?ruc={ruc}` — Search Panama by RUC.
`GET /v4/ecuador/entidades?nombre={name}` — Same, scoped to Ecuadorian organizations.
`GET /v4/ecuador/entidades?ruc={ruc}` — RUC search for Ecuador organizations (13 digits, ends in `001`).

Returns an array of matching entities with `id`, `nombre`, `ruc`/`cedula`, and `tipo`.

### Get entity detail
`GET /v4/panama/entidades/{id}?include={codes}` — Fetch detailed data (Panama: organizations and natural persons).
`GET /v4/ecuador/entidades/{id}?include={codes}` — Fetch detailed data (Ecuador: organizations only).

The `include` parameter is required and accepts comma-separated product codes. The set of accepted codes varies by jurisdiction — see Coverage below. On an unsupported code the API returns `400` with a `supported_includes` array listing the codes the jurisdiction recognises.

### Request a data refresh (Panama)
`POST /v4/panama/entidades/{id}/update?include={codes}` — Queue an on-demand scrape; result is delivered via webhook or polled with the endpoint below.

### Poll an update request
`GET /v4/update_requests/{update_request_id}` — Returns the status (`pending`/`completed`/`failed`) and result of an update request.

### Ecuador
`GET /v4/ecuador/entidades?nombre={name}` and `GET /v4/ecuador/entidades?ruc={ruc}` to search; `GET /v4/ecuador/entidades/{id}?include={codes}` to fetch detail. Reduced catalog today — check `GET /v5/catalog` for what is live.

### Colombia
Not yet generally available — sources, data levels, and product codes are still being defined (see Coverage below). The v4 contract reserves `GET /v4/colombia/entidades` (search by name or `ruc`; the numeric param is `ruc` for cross-jurisdiction consistency and matches the Colombian NIT) and `GET /v4/colombia/entidades/{id}?include={codes}`, following the same structure as Panama.

## Product codes and pricing

Every request has a **$0.01 base charge**. Product code costs are added on top.

The live catalog (codes, data levels, and current costs) is served by the API itself: `GET /v5/catalog` (free). Any call also accepts `dry_run=true` to preview its exact charge without spending balance.

Smart resolution: overlapping codes are deduplicated — you only pay for non-redundant data.

Ecuador accepts a reduced catalog (organizations only); unsupported codes return `400 unknown product code(s)`.

## Example workflow

```bash
# 1. Search by name (Panama)
curl -H "Authorization: Bearer pk_XXX" \
  "https://api.panadata.net/v4/panama/entidades?nombre=copa+airlines"

# 2. Get details with product codes (Panama)
curl -H "Authorization: Bearer pk_XXX" \
  "https://api.panadata.net/v4/panama/entidades/12345?include=DAT-CORE,DAT-GOV"

# 3. Same flow for Ecuador (organizations only)
curl -H "Authorization: Bearer pk_XXX" \
  "https://api.panadata.net/v4/ecuador/entidades?ruc=1768040920001"

curl -H "Authorization: Bearer pk_XXX" \
  "https://api.panadata.net/v4/ecuador/entidades/52015398?include=DAT-ALL"
```

## Coverage

- **Panama** (full) — 28 data sources, 34 data levels. Organizations and natural persons.
- **Ecuador** (initial — organizations only) — 8 data sources, 12 data levels. Natural persons not part of the public catalog (LOPDP).
- **Colombia** — upcoming.

## Documentation

- [Getting started](https://platform.panadata.net/docs/empezar)
- [MCP server (AI agents)](https://platform.panadata.net/mcp)
- [Authentication guide](https://platform.panadata.net/docs/guias/autenticacion)
- [First query guide](https://platform.panadata.net/docs/guias/primera-consulta)
- [Include parameter guide](https://platform.panadata.net/docs/guias/include-parameter)
- [Sandbox vs API](https://platform.panadata.net/docs/guias/sandbox-vs-api)
- [Error handling](https://platform.panadata.net/docs/guias/errores)
- [Async updates and webhooks](https://platform.panadata.net/docs/guias/webhooks)
- [API reference (OpenAPI)](https://platform.panadata.net/docs/referencia)
- [Jurisdictions](https://platform.panadata.net/docs/conceptos/jurisdicciones)
- [Data sources](https://platform.panadata.net/docs/conceptos/fuentes-de-datos)
- [Data levels](https://platform.panadata.net/docs/conceptos/niveles-de-datos)
- [Identifiers](https://platform.panadata.net/docs/conceptos/identificadores)
- [Billing](https://platform.panadata.net/docs/conceptos/facturacion)

## Machine-readable specs

- [OpenAPI 3.0 (Spanish)](https://platform.panadata.net/openapi.yml)
- [OpenAPI 3.0 (English)](https://platform.panadata.net/openapi.en.yml)
- [AI plugin manifest](https://platform.panadata.net/.well-known/ai-plugin.json)
- [Full docs as a single markdown file](https://platform.panadata.net/llms-full.txt)

Every docs page is also available as markdown by appending `.md` to its URL — e.g. `https://platform.panadata.net/docs/conceptos/niveles-de-datos.md`.