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

# Introduction

> Everything you need to start building with the Swoogo API

The Swoogo API provides programmatic access to manage events, registrants, sessions, speakers, sponsors, and related resources on the Swoogo event management platform.

**Base URL:** `https://api.swoogo.com/api/v1`

## Getting started

<Steps>
  <Step title="Get your API credentials" icon="key">
    Log in to Swoogo and navigate to **My Profile > API Credentials** to find your consumer key and secret. Swoogo also provides a pre-encoded Base64 credential string you can use directly.

    <Tip>Your API Credentials page provides a ready-to-use Base64-encoded string — copy it directly to skip the manual encoding step.</Tip>
  </Step>

  <Step title="Request an access token" icon="lock">
    Exchange your credentials for a bearer token by calling `POST /oauth2/token`.

    <CodeGroup>
      ```bash cURL theme={null}
      # Use the Base64-encoded credentials from your API Credentials page
      curl -X POST "https://api.swoogo.com/api/v1/oauth2/token" \
        -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
        -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
        -d "grant_type=client_credentials"
      ```

      ```javascript Node.js theme={null}
      const credentials = Buffer.from(
        `${CONSUMER_KEY}:${CONSUMER_SECRET}`
      ).toString('base64');

      const response = await fetch('https://api.swoogo.com/api/v1/oauth2/token', {
        method: 'POST',
        headers: {
          'Authorization': `Basic ${credentials}`,
          'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8',
        },
        body: 'grant_type=client_credentials',
      });

      const { access_token, expires_at } = await response.json();
      ```

      ```python Python theme={null}
      import base64
      import requests

      credentials = base64.b64encode(
          f"{CONSUMER_KEY}:{CONSUMER_SECRET}".encode()
      ).decode()

      response = requests.post(
          "https://api.swoogo.com/api/v1/oauth2/token",
          headers={
              "Authorization": f"Basic {credentials}",
              "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
          },
          data="grant_type=client_credentials",
      )

      token = response.json()["access_token"]
      ```
    </CodeGroup>

    The response includes your token and its expiration:

    ```json theme={null}
    {
      "access_token": "your-access-token",
      "type": "bearer",
      "expires_at": "2024-11-08 16:04:40"
    }
    ```

    <Warning>Tokens expire after **30 minutes**. Request a new token when you receive a `401` response.</Warning>
  </Step>

  <Step title="Make your first API call" icon="rocket">
    Include your token in the `Authorization` header on all subsequent requests.

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.swoogo.com/api/v1/events" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.swoogo.com/api/v1/events', {
        headers: {
          'Authorization': `Bearer ${access_token}`,
        },
      });

      const data = await response.json();
      ```

      ```python Python theme={null}
      response = requests.get(
          "https://api.swoogo.com/api/v1/events",
          headers={"Authorization": f"Bearer {token}"},
      )

      data = response.json()
      ```
    </CodeGroup>
  </Step>
</Steps>

## Rate limiting

API requests are rate-limited to **2,000 requests per 10-minute window** per API credential. List endpoints cost **10 credits** per call; all other endpoints cost **1 credit**.

Rate limit status is returned in response headers:

| Header                   | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `X-Rate-Limit-Limit`     | Maximum requests allowed in the current window |
| `X-Rate-Limit-Remaining` | Requests remaining in the current window       |
| `X-Rate-Limit-Reset`     | Seconds until the window resets                |

When the limit is exceeded, the API returns `429 Too Many Requests`.

## Pagination

All list endpoints return paginated results in this envelope:

```json theme={null}
{
  "items": [...],
  "_links": {
    "self": { "href": "..." },
    "first": { "href": "..." },
    "last": { "href": "..." }
  },
  "_meta": {
    "totalCount": 95,
    "pageCount": 5,
    "currentPage": 1,
    "perPage": 20
  }
}
```

| Parameter  | Default | Max  | Description                                            |
| ---------- | ------- | ---- | ------------------------------------------------------ |
| `page`     | 1       | —    | Page number (1-indexed)                                |
| `per-page` | 20      | 1000 | Items per page. Capped at **200** when using `expand`. |

## Filtering and sorting

Use the `search` parameter to filter results. Combine multiple conditions with `&`.

**Operators:** `=`, `!=`, `>`, `<`, `>=`, `<=`, `*contains*`, `*beginswith*`, `*endswith*`, `*in*`

```bash theme={null}
# Exact match
search=registration_status=confirmed

# Date range
search=created_at>=2024-01-01

# Starts with
search=last_name=*beginswith*Sm

# Multiple values (OR)
search=status=*in*confirmed|attended

# Multiple conditions (AND by default)
search=id>100&registration_status=confirmed
```

Set `searchCondition=or` to match **any** condition instead of all.

Use `sort` to order results. Prefix with `-` for descending: `sort=-created_at`.

## Field selection and expansion

Use `fields` to request only the fields you need:

```
fields=id,email,first_name,last_name
```

Use `expand` to include related objects in the response:

```
expand=homeAddress,sessions
```

<Info>Using `expand` caps the page size at **200** items per page.</Info>

## Errors

All errors return a consistent JSON response:

```json theme={null}
{
  "name": "Not Found",
  "message": "The requested resource does not exist.",
  "code": 0,
  "status": 404
}
```

| Status | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| `400`  | Bad Request — invalid parameters or business rule violation |
| `401`  | Unauthorized — missing or expired bearer token              |
| `403`  | Forbidden — valid token but insufficient permissions        |
| `404`  | Not Found — resource does not exist or is not accessible    |
| `422`  | Unprocessable Entity — validation errors on input fields    |
| `429`  | Too Many Requests — rate limit exceeded                     |
| `500`  | Internal Server Error — unexpected server error             |

## Webhooks

Swoogo can send HTTP callbacks when resources are created, updated, or deleted. Configure webhooks via the API or the Swoogo UI.

Supported trigger objects: `event`, `contact`, `registrant`, `speaker`, `sponsor`, `session`, `session_attendance`, `registrant_line_item`.

Webhook payloads can be sent as `json` (application/json) or `post` (form-encoded).