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

# Quickstart

> Create an API key and make your first request.

**1. Create an API key**

In BeanRails, open **Settings** and go to **API Keys**. Click **Create**, name the key after the system that will use it, and choose the scopes it needs. See [Authentication](https://api-docs.beanrails.com/authentication.md) for what each scope allows.

Copy the key when it is shown. BeanRails stores only a hash of it, so you cannot see it again.

> [!NOTE]
>
> You need to be the workspace owner, or have a role that allows creating API keys.

**2. List your contacts**

Send the key as a bearer token. Replace `{host}` with the host your BeanRails workspace is served from.

```bash curl theme={null}
curl "https://{host}/api/public/v1/contacts?limit=5" \
  -H "Authorization: Bearer brk_live_your_key_here" \
  -H "Accept: application/json"
```

```javascript Node.js theme={null}
const res = await fetch("https://{host}/api/public/v1/contacts?limit=5", {
  headers: {
    Authorization: "Bearer brk_live_your_key_here",
    Accept: "application/json"
  }
});
const { data, meta } = await res.json();
```

```python Python theme={null}
import requests

res = requests.get(
    "https://{host}/api/public/v1/contacts",
    params={"limit": 5},
    headers={"Authorization": "Bearer brk_live_your_key_here"},
)
contacts = res.json()["data"]
```

**3. Create a contact**

This needs the `contacts:write` scope.

```bash theme={null}
curl -X POST "https://{host}/api/public/v1/contacts" \
  -H "Authorization: Bearer brk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "company_name": "Acme Trading Sdn Bhd",
    "email": "accounts@acme.example",
    "addresses": [{ "name": "Head office", "address1": "1 Jalan Example", "is_primary": true }]
  }'
```

The response contains the new contact under `data`. Keep its `id`: you use it to create works and invoices for this customer.

## Next steps

> **[Authentication](https://api-docs.beanrails.com/authentication.md)**
>
> Scopes, expiry and what a key is allowed to see.

> **[Conventions](https://api-docs.beanrails.com/conventions.md)**
>
> Pagination, filtering, dates and money.


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