> For the complete documentation index, see [llms.txt](https://developer.maisonsafqa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.maisonsafqa.com/getting-started.md).

# Getting Started

### Base URL

All API requests should be made to:

```
https://api.maisonsafqa.com/v1
```

### Authentication

All API endpoints require authentication using an API key. Include your API key in the `X-MaisonSafqa-Api-Key` header with every request.

#### API Key Formats

| Environment | Key Prefix    | Usage                        |
| ----------- | ------------- | ---------------------------- |
| Development | `ms_test_...` | Testing and development only |
| Production  | `ms_live_...` | Live production environment  |

> ⚠️ **Important**: API keys are environment-specific. A test key will not work in production, and vice versa.

#### Getting Your API Key

Contact the Maison Safqa team at <itsupport@maisonsafqa.com> to request API access for your brand.

When you receive your API key, store it securely. The full key is only shown once at creation time.

### Quick Start Example

Here's a simple example to create your first product:

```bash
curl -X POST https://api.maisonsafqa.com/v1/products \
  -H "Content-Type: application/json" \
  -H "X-MaisonSafqa-Api-Key: ms_test_your_api_key_here" \
  -d '{
    "title": "Premium Cotton T-Shirt",
    "body_html": "<p>High quality cotton t-shirt.</p>",
    "vendor": "Your Brand Name",
    "product_type": "Apparel",
    "tags": "cotton,premium,t-shirt",
    "variants": [
      {
        "title": "Small",
        "sku": "TSHIRT-001-S",
        "price": 99.99,
        "inventory_quantity": 25
      },
      {
        "title": "Medium",
        "sku": "TSHIRT-001-M",
        "price": 99.99,
        "inventory_quantity": 50
      },
      {
        "title": "Large",
        "sku": "TSHIRT-001-L",
        "price": 99.99,
        "inventory_quantity": 30
      }
    ],
    "images": [
      {
        "src": "https://example.com/images/tshirt-front.jpg",
        "alt": "T-shirt front view",
        "position": 1
      }
    ]
  }'
```

#### Response

A successful response returns status `201 Created`:

```json
{
  "error": null,
  "product": {
    "id": "product_1234567890123456",
    "title": "Premium Cotton T-Shirt",
    "handle": "premium-cotton-t-shirt",
    "status": "draft",
    "variants": [
      {
        "sku": "TSHIRT-001-S",
        "price": 99.99,
        "inventory_quantity": 25
      }
    ],
    "synced": false,
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Product created successfully. It will be synced to Shopify when activated."
}
```

### Rate Limits

The API enforces rate limiting to ensure fair usage:

| Limit                    | Value |
| ------------------------ | ----- |
| Requests per minute      | 300   |
| Bulk operation max items | 500   |

#### Rate Limit Headers

Every response includes rate limit information:

| Header                  | Description                               |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed per minute (300) |
| `X-RateLimit-Remaining` | Requests remaining in current window      |
| `X-RateLimit-Reset`     | Unix timestamp when the limit resets      |

If you exceed the rate limit, you'll receive a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait.

### Key Concepts

#### Product Status

Products are created in `draft` status and will be synced to Shopify when activated by the Maison Safqa team.

#### Inventory Sync

Inventory updates are stored locally and periodically synced to Shopify. Your brand's inventory data always takes precedence in case of conflicts.

#### Bulk Operations

For efficiency, you can create up to 500 products or update inventory for up to 500 products in a single request. Bulk operations support **partial success** - valid items are processed even if some fail validation.

### Error Handling

All errors follow a consistent format:

```json
{
  "error": {
    "field": "variants.sku",
    "message": "SKUs already exist for this brand: TSHIRT-001-S"
  }
}
```

Common HTTP status codes:

| Code  | Description                                                       |
| ----- | ----------------------------------------------------------------- |
| `200` | Success                                                           |
| `201` | Created                                                           |
| `207` | Multi-Status (partial success in bulk operations)                 |
| `400` | Bad Request - Validation errors                                   |
| `401` | Unauthorized - Invalid or missing API key                         |
| `404` | Not Found - Product doesn't exist or doesn't belong to your brand |
| `429` | Too Many Requests - Rate limit exceeded                           |
| `500` | Internal Server Error                                             |

### Next Steps

* **Products API** - Create, retrieve, and update products
* **Inventory API** - Manage inventory levels
* **Error Reference** - Complete list of error codes and messages

### Support

If you have questions or need assistance:

* **Email**: <itsupport@maisonsafqa.com>
* **Documentation Issues**: Open an issue on our developer portal


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.maisonsafqa.com/getting-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.