# API reference

> The address, the token, the shape of every answer, and what an error looks like.

Source: https://storeware.ai/docs/api-reference

Your app calls the same API the Storeware admin does, limited to the scopes its installation was granted.

## Address and token

```http
GET https://api.storeware.ai/api/v1/stores/{storeId}/products
Authorization: Bearer <access token>
```

The access token is the one your app received for that shop: see [Installs and tokens](https://storeware.ai/docs/build-apps/installs-and-tokens). It lasts 24 hours; the [SDK](https://storeware.ai/docs/sdk) refreshes it for you.

## Answers

A successful answer is JSON with the result under `data`. A list carries counts under `meta`:

```json
{
  "data": [{ "id": "8c1f...", "title": "Linen apron" }],
  "meta": { "total": 41 }
}
```

Lists take `limit` and `offset`. Fifty rows come back when no `limit` is given.

## Errors

An error is JSON with a `type` a program can test, a `message` a person can read, and the `requestId` to quote when you ask for help:

```json
{
  "error": { "type": "not_found", "message": "Not found" },
  "requestId": "3f6c2a9e-..."
}
```

| Status | `type`              | What happened                                                                        |
| ------ | ------------------- | ------------------------------------------------------------------------------------ |
| 400    | `bad_request`       | The request could not be read.                                                       |
| 401    | `unauthorized`      | No token, or one that has ended.                                                     |
| 403    | `forbidden`         | The token's scopes do not cover this. `requiredScopes` names what it would need.     |
| 404    | `not_found`         | Nothing by that id, or nothing this token may see.                                   |
| 409    | `conflict`          | It clashes with the current state; read it again.                                    |
| 422    | `validation_failed` | The body was read but is wrong. `fields` names each field and what is wrong with it. |
| 429    | `rate_limited`      | Too many calls. Wait for the seconds in `Retry-After`.                               |

## Limits

Each installation may make 240 calls a minute. Past that the API answers 429 with `Retry-After`, in seconds. Send `x-request-id` with a call to have it used as the `requestId`.

## Every call

The [REST reference](https://storeware.ai/docs/api-reference/rest) lists each call an app can make, what it takes, what it answers and the permissions it needs. The same calls are an OpenAPI 3.1 document at `https://api.storeware.ai/api/v1/openapi.json`, for a code generator or an API client.

## Storefront GraphQL

What a shopper sees is also a graph, at `https://api.storeware.ai/graphql/storefront`, for the shop front and the agents that shop for people. It takes an agent key or a shop's publishable token rather than your app's token. See [Storefront GraphQL](https://storeware.ai/docs/api-reference/storefront-graphql).