# Make your first API call

A versioned REST API for profiles, organisations and events. JSON over HTTPS with a bearer token.

Canonical: https://chikaraintel.com/docs/api

## Base URL

Base URL:

```text
https://api.chikaraintel.com
```

Every path starts with `/v1`. Requests and responses are JSON. Dates in parameters are `YYYY-MM-DD`.

## 1. Get a token

Create an API key on the [MCP Access page](https://app.chikaraintel.com/account/mcp) and export it. The same key works for the API and the MCP server.

Terminal:

```bash
export CHIKARA_API_TOKEN="<your-token>"
```

## 2. Find a company

**cURL**

```bash
curl -sS -G "https://api.chikaraintel.com/v1/organisations" \
  -H "Authorization: Bearer $CHIKARA_API_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "name=Halberd" \
  --data-urlencode "show_empty=true" \
  --data-urlencode "limit=5"
```

**JavaScript**

```javascript
const params = new URLSearchParams({ name: "Halberd", show_empty: "true", limit: "5" });
const res = await fetch(`https://api.chikaraintel.com/v1/organisations?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.CHIKARA_API_TOKEN}`,
    Accept: "application/json"
  }
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const { success } = await res.json();
for (const org of success) console.log(org.reference, org.name);
```

**Python**

```python
import os
import requests

res = requests.get(
    "https://api.chikaraintel.com/v1/organisations",
    headers={"Authorization": f"Bearer {os.environ['CHIKARA_API_TOKEN']}"},
    params={"name": "Halberd", "show_empty": "true", "limit": 5},
    timeout=30,
)
res.raise_for_status()

for org in res.json()["success"]:
    print(org["reference"], org["name"])
```

## 3. Read the response

Every response wraps its payload in `success`. List endpoints add `meta` for paging.

Response:

```json
{
  "status": {
    "code": 200,
    "messages": []
  },
  "success": [
    {
      "reference": "3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b01",
      "name": "Halberd Industrial Group",
      "totals": {
        "employees": 3200
      },
      "status": "active",
      "verified": true,
      "confidence": 88
    }
  ],
  "meta": {
    "total": 1,
    "rows_per_page": 5,
    "page": 1,
    "total_pages": 1,
    "links": {}
  },
  "correlation_id": "5f0c2a9e4b7d4c1e"
}
```

## 4. Get that company's recent moves

Pass the reference to the events list.

cURL:

```bash
curl -sS -G "https://api.chikaraintel.com/v1/events" \
  -H "Authorization: Bearer $CHIKARA_API_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "organisationReference=3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b01" \
  --data-urlencode "eventType=move" \
  --data-urlencode "limit=20"
```

## Next

- [Pagination](/docs/api/pagination): loop through a long list safely.
- [Errors](/docs/api/errors): what comes back when a call fails.
- [Reference](/docs/api/reference): every public endpoint, with parameters and samples.

## Related

- https://chikaraintel.com/docs/api/pagination.md
- https://chikaraintel.com/docs/api/errors.md
- https://chikaraintel.com/docs/api/reference.md