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

# Introduction

## Welcome

The Juo Admin API provides programmatic access to manage subscription resources. This RESTful API allows administrators to interact with subscriptions, customers, and other Juo entities.

<Card icon="npm" horizontal>
  Admin API SDK is available [here](https://www.npmjs.com/package/@juo/admin-api).
</Card>

## Authentication

All API requests must include an API key in the `X-Juo-Admin-Api-Key` header. Tokens can be generated in the Juo admin interface. Keep your API keys secure and never share them.

```
X-Juo-Admin-Api-Key: your_api_key
```

## Pagination

The API uses cursor-based pagination to handle large result sets. Navigation links are provided in the `Link` response header, containing URLs for the next and previous pages.

```
Link: <https://api.juo.io/admin/v1/subscriptions?cursor=<next-cursor>>; rel="next",
      <https://api.juo.io/admin/v1/subscriptions?cursor=<prev-cursor>>; rel="prev"
```

The amount of results per page can be set from 1-100 with the `limit` query parameter where applicable:

```
/admin/v1/subscriptions?limit=10
```

## Sorting

Results can be sorted using the `sort` query parameter. Multiple sort criteria can be combined using commas.

Sortable fields are the same as the filterable fields on a resource, there is a special `rank` field that can be always used whenever search query includes a term not bound to a specific field.

```
# Sort by creation date descending
/admin/v1/subscriptions?sort=createdAt:desc

# Sort by status ascending and then by creation date descending
/admin/v1/subscriptions?sort=status:asc,createdAt:desc
```

## Search query language

Resources can be searched / filtered by an expressive query syntax.

The search grammar is expressed in [EBNF](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form). It uses the following terminal symbols:

| Symbol | Description                                                 |
| ------ | ----------------------------------------------------------- |
| \_     | Optional whitespace                                         |
| \_\_   | Mandatory whitespace                                        |
| field  | An identifier (`[a-z][a-zA-Z]*`)                            |
| value  | An identifier, single quoted string or double quoted string |

The syntax can be expressed with the following grammar:

```ebnf theme={null}
Query       = Disjunction
Negation    = ( "-" | "NOT" ) _ Parenthesis | Parenthesis
Parenthesis = "(" _ Query _ ")" | Term
Disjunction = Conjunction ( __ "OR" __ Conjunction ):+ | Conjunction
Conjunction = Negation ( __ "AND" __ Negation ):+ | Negation
Term        = field Operator value | value
Operator    = ":" | ":<" | ":>" | ":>=" | ":<="
```

It lets you to form advanced logical queries, some examples below:

```
# Find all active subscriptions which contain a term "Blue"
status:active AND Blue

# The same as above but with quotes
status:'active' AND 'Blue'

# Find failed subscriptions with PayPal instrument along with all cancelled subscriptions after 2024
(status:failed AND instrument:paypal) OR (status:cancelled AND cancelledAt:>='2024-01-01')

# Find all but active subscriptions
- status:active
```

Below you can find the meaning of each available operator:

| Operator | Description           |
| -------- | --------------------- |
| :        | Equal                 |
| :>       | Greater than          |
| :>=      | Greater than or equal |
| :\<      | Less than             |
| :\<=     | Less than or equal    |

## Rate limiting

The API implements a token bucket rate-limiting strategy to ensure fair usage. Each API token has a bucket that fills at a constant rate. API calls consume tokens from the bucket. When the bucket is empty, requests will be rejected until it refills.

Rate limit information is included in the response headers:

```
X-RateLimit-Limit: 1000     # How many requests the client can make
X-RateLimit-Remaining: 999  # How many requests remain to the client in the time window
X-RateLimit-Reset: 60       # How many seconds must pass before the rate limit resets
```