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

# Overview

> Base URL, versioning, response format, and client libraries for the Swish REST API.

The Swish REST API gives you direct access to profiles, wishlists, saved items, notifications, subscriptions, and more. All endpoints return JSON and require authentication via a Bearer token.

> [!NOTE]
>
> For most integrations, use the [Swish SDK](https://swish.app/docs/references/sdk/overview.md) or
> [React SDK](https://swish.app/docs/references/react/overview.md) instead of calling the REST API directly.
> The SDKs handle authentication, caching, state management, and UI rendering
> out of the box. The REST API is intended for server-side integrations, custom
> backends, or environments where the SDKs are not available.

## Base URL

```
https://swish.app/api/2026-07
```

Every request must target a versioned base URL.

## Versioning

Each version is a stable snapshot of the API surface - once published, it does not receive breaking changes.

These versions have a typed client in `@swishapp/api-client`:

| Version | Status | Notes |
| - | - | - |
| `2026-07` | Latest | Current stable version. Used by `@swishapp/sdk` and the unpinned api-client entry. |
| `2026-04` | Supported | Analytics endpoints moved to admin-only scope in `2026-07`, so they are still storefront-facing here. |
| `2026-01` | Supported | |
| `unstable` | Prerelease | Prerelease build of the current version, served from `unstable.swish.app`. Subject to change. |

Earlier versions (`2025-04`, `2025-07`, `2025-10`) are still accepted by the API but have no shipped client - call them over HTTP directly. Contact [support@swish.app](mailto:support@swish.app) before relying on one.

The version is part of the URL path. All requests to `/api/2026-07/...` use that version.

> [!NOTE]
>
> The endpoint reference in this section is generated from the `2026-07` OpenAPI
> spec. To target an older version, swap the version segment in the base URL and
> import the matching api-client entry point (for example
> `@swishapp/api-client/2026-04`).

## Response format

Successful responses wrap the result in a `data` property:

```json theme={null}
{
  "data": {
    "id": "67a61d5561e4f9de302c02a1",
    "title": "My Wishlist"
  }
}
```

Endpoints that return collections include a `pageInfo` object alongside `data`:

```json theme={null}
{
  "data": [{ "id": "67a61d5561e4f9de302c02a1", "title": "My Wishlist" }],
  "pageInfo": {
    "next": "YWZ0ZXI6NjdhNjFkNTU2MWU0ZjlkZTMwMmMwMmEx",
    "previous": null,
    "totalCount": 42
  }
}
```

See [Pagination](https://swish.app/docs/references/api/pagination.md) for details on iterating through pages.

Error responses use a consistent envelope described in [Errors](https://swish.app/docs/references/api/errors.md).

## Client libraries

The `@swishapp/api-client` package provides a typed TypeScript client for the Swish API. Install it and import the version you need:

```bash npm theme={null}
npm install @swishapp/api-client
```

```bash pnpm theme={null}
pnpm add @swishapp/api-client
```

```bash yarn theme={null}
yarn add @swishapp/api-client
```

```typescript theme={null}
import { createApiClient } from "@swishapp/api-client/2026-07";

const client = createApiClient({
  authToken: "your-api-token",
});

const { data, pageInfo } = await client.items.list({ limit: 10 });
```

The client handles authentication headers, response unwrapping, and pagination types automatically.

## Next steps

> [card] [Authentication](https://swish.app/docs/references/api/authentication.md)
>
> Set up API keys and client tokens to authenticate requests.

> [card] [Pagination](https://swish.app/docs/references/api/pagination.md)
>
> Iterate through paginated collections using cursors.

> [card] [Rate limits](https://swish.app/docs/references/api/rate-limits.md)
>
> Understand request limits and how to handle throttling.

> [card] [Errors](https://swish.app/docs/references/api/errors.md)
>
> Handle error responses and status codes.


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