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

# API Introduction

> Get started with PromoStack Mobile SDK API

# PromoStack Mobile SDK

PromoStack provides a simple REST API for integrating referral programs into your mobile app.

## Base URL

```
https://api.promostack.app
```

## Quick Integration

<Steps>
  <Step title="Get API Key">
    Create an app in the [PromoStack Dashboard](https://www.promostack.app/dashboard) and copy your API key.
  </Step>

  <Step title="Get/Create Referrer">
    When user opens referral program, call `/referrer` to get their link and current progress.
  </Step>

  <Step title="Redeem Metacode">
    When user enters referral code, call `/referee-redeem` to get platform-specific promo code.
  </Step>
</Steps>

## API Endpoints

\| Endpoint | Purpose |
\|----------|---------||
\| `POST /referrer` | Get or create referrer and fetch progress stats |
\| `POST /referrer-claim` | Claim available rewards |
\| `POST /referee-redeem` | Redeem metacode and get promo code |

## Error Handling

All endpoints return consistent error format:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}
```

Common error codes:

* `400 VALIDATION_ERROR` - Missing or invalid parameters
* `401 UNAUTHORIZED` - Invalid or missing API key
* `404 NOT_FOUND` - Resource not found
* `409 CONFLICT` - Duplicate or conflicting request
* `503 SERVICE_UNAVAILABLE` - Temporary service issue

## Rate Limits

* **Free tier**: 1,000 requests/month
* **Basic tier**: 10,000 requests/month
* **Pro tier**: 100,000 requests/month

Rate limit headers included in all responses:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```