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

# API Reference

> Complete reference for the Sticker Partner API

## Overview

The Sticker Partner API allows you to programmatically provision organizations, authenticate users, and manage the embedded procurement experience.

## Base URL

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

All API endpoints are versioned under `/v1`.

## Authentication

All API requests require authentication via API key.

### Organization Setup

Uses `Authorization: Bearer` header:

```bash theme={null}
Authorization: Bearer sk_live_your_api_key
```

### Partner Handshake

Uses `X-API-Key` header:

```bash theme={null}
X-API-Key: sk_live_your_api_key
```

<Info>
  Contact us to receive your API credentials: [suyash@usesticker.com](mailto:suyash@usesticker.com)
</Info>

## Available Endpoints

<CardGroup cols={2}>
  <Card title="Organization Setup" icon="building" href="/api-reference/organization-setup">
    ```
    POST /v1/organizations/setup
    ```

    Provision organizations, users, and shipping locations
  </Card>

  <Card title="Partner Handshake" icon="handshake" href="/api-reference/handshake">
    ```
    POST /v1/partner/handshake
    ```

    Authenticate users and receive session tokens
  </Card>
</CardGroup>

## Request Format

All requests must:

* Use `Content-Type: application/json`
* Send JSON-encoded request bodies
* Include proper authentication headers

```bash theme={null}
curl -X POST https://api.usesticker.com/v1/organizations/setup \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

## Response Format

All responses are JSON with the following structure:

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    // Response data here
  }
}
```

### Error Response

```json theme={null}
{
  "error": "Error Type",
  "message": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": [
    // Validation errors or additional info
  ]
}
```

## HTTP Status Codes

| Status | Description                               |
| ------ | ----------------------------------------- |
| `200`  | Success                                   |
| `400`  | Bad Request - Invalid parameters          |
| `401`  | Unauthorized - Invalid or missing API key |
| `403`  | Forbidden - Insufficient permissions      |
| `404`  | Not Found - Resource doesn't exist        |
| `409`  | Conflict - Resource already exists        |
| `429`  | Too Many Requests - Rate limited          |
| `500`  | Server Error - Something went wrong       |

## Rate Limits

| Endpoint                  | Rate Limit          |
| ------------------------- | ------------------- |
| `/v1/organizations/setup` | 100 requests/minute |
| `/v1/partner/handshake`   | 300 requests/minute |

When rate limited, the response includes:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}
```

## Error Handling

We recommend implementing retry logic with exponential backoff:

```javascript theme={null}
async function apiCall(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        // Rate limited - wait and retry
        const delay = Math.pow(2, i) * 1000;
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      if (error.status >= 500 && i < maxRetries - 1) {
        // Server error - wait and retry
        const delay = Math.pow(2, i) * 1000;
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
}
```

## Environments

| Environment         | Base URL                                | API Keys    |
| ------------------- | --------------------------------------- | ----------- |
| **Production**      | `https://api.usesticker.com/v1`         | `sk_live_*` |
| **Staging/Sandbox** | `https://api.staging.usesticker.com/v1` | `sk_test_*` |

<Warning>
  Use sandbox credentials for development and testing. Never use production API keys in test environments.
</Warning>

## Need Help?

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope" href="mailto:suyash@usesticker.com">
    Get help from our integration team
  </Card>

  <Card title="Schedule a Call" icon="phone" href="https://calendly.com/usesticker/meeting">
    Book time with our engineers
  </Card>
</CardGroup>