> For the complete documentation index, see [llms.txt](https://api-docs.easyday.dk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.easyday.dk/get-started.md).

# Get started

The Easyday API gives you programmatic, read/write access to your product data, orders, customers, files and shared reference data — the same data you manage in your admin panel, available for your own systems (ERP, webshop, warehouse, etc.) to integrate with.

* **Base URL:** `https://api.easyday.com`
* **Format:** JSON over HTTPS
* **Versioning:** all endpoints are versioned under `/v1/`

### Areas

| Area     | Base path       | What it covers                                                            |
| -------- | --------------- | ------------------------------------------------------------------------- |
| PIM      | `/v1/pim/`      | Products, prices, stock, categories                                       |
| Commerce | `/v1/commerce/` | Orders, customers                                                         |
| Core     | `/v1/core/`     | Shared reference data: languages, currencies, countries, channels, groups |
| Files    | `/v1/files/`    | Upload, download and manage files and folders                             |

See **API Reference** in the sidebar for the full list of endpoints, parameters and response schemas.

### Authentication

Every request must include an API key as a Bearer token:

```
Authorization: Bearer <your-api-key>
```

Requests without a valid key, or with an expired or revoked key, receive `401 Unauthorized`.

#### Getting an API key

1. In your admin panel, go to **Settings → Users**.
2. Create a new user and choose **API user** as the type.
3. Select the scopes this key needs (see below) and, optionally, an expiry date and an IP allowlist.
4. Save. Your API key is shown **once**, at creation time — copy it somewhere safe. If you lose it, you can regenerate a new one from the same screen, which immediately invalidates the old one.

Each API key is tied to one user and can be revoked at any time from the same screen. Keys can also be set to expire automatically; if you configured an expiry date, you'll get an email warning 14, 7 and 1 day before it lapses.

#### Scopes

Access is controlled per key by scope:

| Scope                              | Grants                                                           |
| ---------------------------------- | ---------------------------------------------------------------- |
| `pim:read` / `pim:write`           | Read / write access to PIM (products, prices, stock, categories) |
| `commerce:read` / `commerce:write` | Read / write access to Commerce (orders, customers)              |
| `core:read`                        | Read access to shared reference data                             |
| `files:read` / `files:write`       | Read / write access to files and folders                         |

A key only has the scopes you explicitly grant it. Calling an endpoint without the required scope returns `403 Forbidden`.

#### Example request

```bash
curl https://api.easyday.com/v1/pim/products \
  -H "Authorization: Bearer <your-api-key>"
```

### Rate limits

Requests are rate-limited per API key (default: 60 requests/minute, with bursts up to 100). If you exceed the limit, you'll receive `429 Too Many Requests`. Need a higher limit? Contact us.

### IP allowlisting

For extra security, you can restrict an API key to specific IP addresses or ranges when creating or editing it in **Settings → Users**. Requests from any other address are rejected with `403 Forbidden`.

### Errors

Errors are returned as JSON:

```json
{
  "error": "Human-readable description of what went wrong."
}
```

Common status codes: `400` (invalid request), `401` (missing/invalid/expired key), `403` (missing scope or IP not allowed), `404` (not found), `422` (request understood but rejected, e.g. a file failing a virus scan), `429` (rate limited).