# Acme Store API

> Manage products, orders and customers of an Acme storefront.

This is the documentation of the API, including a reference generated from a Yaak workspace. Every page is available as Markdown by appending `.md` to its URL.

## Guides › Getting started

- [Introduction](/index.md): Everything you need to build on the Acme Store API.
- [Quickstart](/quickstart.md): Make your first request in under a minute.

## Guides › Guides

- [Authentication](/guides/authentication.md): Get an access token and keep it fresh.
- [Pagination](/guides/pagination.md): Page through long lists with page and limit.

## Changelog

- [Changelog](/changelog.md): Notable changes to the Acme Store API.

## Endpoints

- [Health check](/reference/health-check.md): Returns ok when the API is up.

## Authentication

Obtain and refresh access tokens.

- [Authentication overview](/reference/authentication.md)
- [Log in](/reference/authentication/log-in.md): Exchange user credentials for an access token.
- [Refresh token](/reference/authentication/refresh-token.md): Get a new access token using a refresh token (OAuth 2 style form body).

## Products

Products are the items sold in your store.

- [Products overview](/reference/products.md)
- [List products](/reference/products/list-products.md): Returns a paginated list of products, newest first.
- [Get a product](/reference/products/get-a-product.md): Retrieve a single product by its id.
- [Create a product](/reference/products/create-a-product.md): Create a new product.
- [Update a product](/reference/products/update-a-product.md): Partially update a product.
- [Delete a product](/reference/products/delete-a-product.md): Permanently delete a product.
- [Images](/reference/products/images.md): Upload and manage product images.
  - [Upload an image](/reference/products/images/upload-an-image.md): Upload a product image (PNG or JPEG, max 5 MB).

## Catalog

Browse the product catalog by category.

- [Catalog overview](/reference/catalog.md)
- [Categories](/reference/catalog/categories.md): Top-level product categories.
  - [List categories](/reference/catalog/categories/list-categories.md): Returns all top-level categories.
  - [Subcategories](/reference/catalog/categories/subcategories.md): Categories within a category.
    - [List subcategories](/reference/catalog/categories/subcategories/list-subcategories.md): Returns the subcategories of a category.
    - [Attributes](/reference/catalog/categories/subcategories/attributes.md): Filterable attributes of a subcategory (size, color, …).
      - [List attribute values](/reference/catalog/categories/subcategories/attributes/list-attribute-values.md): Returns the values of every filterable attribute in a subcategory.

## Orders

Orders placed by customers.

- [Orders overview](/reference/orders.md)
- [List orders](/reference/orders/list-orders.md): List orders, optionally filtered by status.
- [Create an order](/reference/orders/create-an-order.md): Place an order on behalf of a customer.
- [Export orders (XML)](/reference/orders/export-orders-xml.md): Legacy XML export.

## GraphQL

A GraphQL endpoint is available for flexible queries.

- [GraphQL overview](/reference/graphql.md)
- [Search products](/reference/graphql/search-products.md): Full-text product search with GraphQL.

## Realtime

Streaming APIs over WebSockets and gRPC.

- [Realtime overview](/reference/realtime.md)
- [Order updates](/reference/realtime/order-updates.md): Subscribe to real-time order events.
- [Get stock level](/reference/realtime/get-stock-level.md): Query live inventory via gRPC.

## Optional

- [Full documentation](/llms-full.txt): All endpoints in a single file