# Basic Concepts

## Base URL

```
https://api.pluggy.ai
```

One environment. Test against the [Sandbox connectors](/docs/guides/sandbox) rather than a separate host.

## Transport

HTTPS with TLS 1.2 or later. Connections negotiating an older TLS version are rejected.

## Requests

REST over JSON. Send `Content-Type: application/json` on every request with a body, and the credential in `X-API-KEY` — see [Authentication](/reference/authentication). Verbs mean what they say: `GET` reads, `POST` creates, `PATCH` updates, `DELETE` removes.

## Responses

JSON. The API evolves without versions by **adding** fields to responses; nothing is removed or renamed. Your client has to accept and ignore fields it does not know — most HTTP libraries do by default, a strict deserializer may not.

Errors share one shape, whatever the endpoint:

```json
{
  "code": 401,
  "codeDescription": "CLIENT_KEYS_UNAUTHORIZED",
  "message": "Client keys are invalid"
}
```

`code` repeats the HTTP status; `codeDescription`, when present, is the stable identifier to branch on; `message` is for people. Some errors add a `data` object. The status codes are listed in [Error Codes](/reference/error-codes).

## Pagination

Two models are in use. The `v2` endpoints paginate with a cursor; every other list endpoint still paginates by page number.

Cursors are how this API paginates from here on, and page-number pagination is being phased out. Where a `v2` cursor endpoint exists, write your integration against it.

### Cursor (`v2` endpoints)

Ask for the first page with your filters. The response carries the records and `next`: a ready-made query string for the following page.

```http
GET https://api.pluggy.ai/v2/transactions
    ?accountId={ACCOUNT_ID}
X-API-KEY: {apiKey}
```

```json
{
  "results": [],
  "next": "?accountId={ACCOUNT_ID}&after={CURSOR}"
}
```

| Field | Meaning |
| --- | --- |
| `results` | The records of this page. |
| `next` | The query string of the next page, or `null` on the last one. |

To continue, append `next` to the endpoint path exactly as received — it already carries your filters and the `after` cursor:

```http
GET https://api.pluggy.ai/v2/transactions
    ?accountId={ACCOUNT_ID}
    &after={CURSOR}
X-API-KEY: {apiKey}
```

Never build or decode `after` yourself: the value is opaque and only valid as returned. A `null` `next` means there is nothing more to read. Cursor pagination is available on [`GET /v2/transactions`](/reference/transaction/transactions-list-by-cursor) and [`GET /v2/items`](/reference/items/items-list-by-cursor) — the latter is opt-in per team; ask support to enable it.

### Page number (other list endpoints)

Investments, investment transactions, payment customers, recipients and requests, and Smart Transfer pre-authorizations paginate by page:

```http
GET https://api.pluggy.ai/investments
    ?itemId={ITEM_ID}
    &page=2
    &pageSize=500
X-API-KEY: {apiKey}
```

```json
{
  "total": 200,
  "totalPages": 15,
  "page": 1,
  "results": []
}
```

| Field | Meaning |
| --- | --- |
| `total` | Records matching the request, across all pages. |
| `totalPages` | Pages needed to read them all. |
| `page` | The page in this response. |
| `results` | The records of this page. |

Two query parameters drive it: `page` (default `1`) and `pageSize` (default `500` where the endpoint accepts it — check the endpoint). To read everything, request `page=1`, then `page=2` … up to `totalPages`.

Every list endpoint outside `v2` paginates this way today, and these are expected to gain cursor equivalents. Keep the paging logic in one place in your integration: moving an endpoint across is then a change in one function rather than at every call site.

<Callout variant="warning" title="GET /transactions is deprecated">
The page-based [`GET /transactions`](/reference/transaction/transactions-list) is available only until **2026-12-31**. Move to [`GET /v2/transactions`](/reference/transaction/transactions-list-by-cursor), which paginates by cursor as above.
</Callout>

Read the guide: [Basic concepts](/docs/developer-tools/basic-concepts).