> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Overview

> Introduction to the Medusa API, including base URLs, request/response formats, and core concepts.

## Introduction

The Medusa API is a RESTful API that provides programmatic access to your commerce backend. It consists of two main sections:

* **Admin API**: For managing your store's products, orders, customers, and other resources
* **Store API**: For building storefronts and customer-facing applications

## Base URLs

The API is accessible through the following base URLs:

```
Admin API: http://localhost:9000/admin
Store API: http://localhost:9000/store
Auth API:  http://localhost:9000/auth
```

<Note>
  Replace `localhost:9000` with your Medusa backend URL in production.
</Note>

## Request Format

All API requests should include the following headers:

```bash theme={null}
Content-Type: application/json
Accept: application/json
```

### Request Body

For POST, PUT, and PATCH requests, the request body should be formatted as JSON:

```json theme={null}
{
  "title": "My Product",
  "description": "A great product",
  "status": "published"
}
```

### Query Parameters

Most list endpoints support the following query parameters:

<ParamField query="fields" type="string">
  Comma-separated list of fields to include in the response. Use dot notation for nested fields (e.g., `id,title,variants.sku`).
</ParamField>

<ParamField query="limit" type="number" default="15">
  Maximum number of items to return.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of items to skip before starting to return results.
</ParamField>

<ParamField query="order" type="string">
  Sort order for results (e.g., `created_at` or `-created_at` for descending).
</ParamField>

## Response Format

All API responses are returned in JSON format with a consistent structure.

### Successful Response

Single resource responses:

```json theme={null}
{
  "product": {
    "id": "prod_123",
    "title": "My Product",
    "status": "published"
  }
}
```

List responses include pagination metadata:

```json theme={null}
{
  "products": [
    {
      "id": "prod_123",
      "title": "Product 1"
    },
    {
      "id": "prod_124",
      "title": "Product 2"
    }
  ],
  "count": 100,
  "offset": 0,
  "limit": 15
}
```

<ResponseField name="count" type="number">
  Total number of items matching the query.
</ResponseField>

<ResponseField name="offset" type="number">
  Number of items skipped.
</ResponseField>

<ResponseField name="limit" type="number">
  Maximum number of items returned.
</ResponseField>

### Error Response

When an error occurs, the API returns an error response:

```json theme={null}
{
  "type": "not_found",
  "message": "Product with id: prod_123 was not found"
}
```

<ResponseField name="type" type="string">
  The error type. Common types include:

  * `not_found` - Resource not found
  * `invalid_data` - Invalid request data
  * `not_allowed` - Operation not permitted
  * `unauthorized` - Authentication required
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable error message.
</ResponseField>

## HTTP Status Codes

The API uses standard HTTP status codes:

| Status Code | Description                            |
| ----------- | -------------------------------------- |
| 200         | Success                                |
| 201         | Resource created                       |
| 400         | Bad request - Invalid parameters       |
| 401         | Unauthorized - Authentication required |
| 403         | Forbidden - Insufficient permissions   |
| 404         | Not found - Resource doesn't exist     |
| 409         | Conflict - Resource already exists     |
| 500         | Internal server error                  |

## Filtering and Search

Many list endpoints support filtering using query parameters:

```bash theme={null}
# Filter products by status
GET /admin/products?status=published

# Filter by multiple values
GET /admin/products?status[]=published&status[]=draft

# Filter orders by date range
GET /admin/orders?created_at[gte]=2024-01-01
```

## Field Selection

Use the `fields` parameter to optimize responses by requesting only needed fields:

```bash theme={null}
# Request specific fields
GET /admin/products?fields=id,title,status

# Request nested fields
GET /admin/products?fields=id,title,variants.id,variants.sku
```

## Rate Limiting

Rate limits may apply depending on your Medusa deployment configuration. When rate limited, the API returns a `429 Too Many Requests` status code.

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/api/authentication">
    Learn how to authenticate API requests
  </Card>

  <Card title="Admin API" icon="shield" href="/api/admin/products">
    Explore the Admin API endpoints
  </Card>

  <Card title="Store API" icon="store" href="/api/store/products">
    Explore the Store API endpoints
  </Card>
</CardGroup>