# List all cheeses

`GET /cheeses`

Returns a paginated list of cheeses in the store. Results can be filtered by status and sorted by name or creation date.

The response includes cursor-based pagination. Use the `nextCursor` value from the response as the `cursor` parameter in subsequent requests.


Authentication (security requirement alternatives):

```json
[
  {
    "api_key": []
  },
  {
    "cheesy_oauth": [
      "read:cheeses"
    ]
  }
]
```

- api_key: apiKey, header X-API-Key. API key authentication. Include your API key in the `X-API-Key` header.

This is an example scheme. Supply credentials from your own service when adapting this contract.

- cheesy_oauth: oauth2. OAuth2 authentication for full API access; scopes: read:cheeses

Parameters:

- `cursor` (query, string, optional) - Pagination cursor from a previous response
  Type: string

- `limit` (query, integer, optional) - Maximum number of cheeses to return
  Type: integer
  
  default: 20
  
  minimum: 1
  
  maximum: 100

- `status` (query, string, optional) - Filter by availability status
  Type: string
  
  enum: ["available","pending","sold"]

- `sort` (query, string, optional) - Sort order for results
  Type: string
  
  default: "name"
  
  enum: ["name","-name","createdAt","-createdAt"]

Responses:

- 200: A paginated list of cheeses

Content type: application/json

Type: object

Paginated list of cheeses

Schema: [CheeseList](https://sourcey.com/examples/docs-showcase/api/schemas/cheeselist-06d8bd48db.md)

- `items` (optional)
  Type: array
  
  Items:
    Reference: [Cheese](https://sourcey.com/examples/docs-showcase/api/schemas/cheese-6e5a59d4fd.md); Type: object

- `nextCursor` (optional)
  Type: string; nullable
  
  Cursor for the next page (null if no more results)

- `hasMore` (optional)
  Type: boolean
  
  Whether there are more results

- `total` (optional)
  Type: integer
  
  Total number of matching cheeses

- 429: Rate limit exceeded

Content type: application/json

Type: object

Schema: [Error](https://sourcey.com/examples/docs-showcase/api/schemas/error-54a0e8c17e.md)

- `code` (required)
  Type: integer, int32
  
  Example:
  
  ```json
  404
  ```

- `type` (optional)
  Type: string
  
  Example:
  
  ```json
  "Not found"
  ```

- `message` (required)
  Type: string
  
  Example:
  
  ```json
  "Your cheese has already been eaten"
  ```

```json
{
  "code": 429,
  "type": "Rate limited",
  "message": "Too many requests, please try again later"
}
```

## Examples

### cURL

```bash
curl -X GET 'https://cheese.example.com/v2/cheeses?limit=20&sort=name' \
  -H 'X-API-Key: YOUR_TOKEN'
```

### TypeScript

```typescript
const response = await fetch('https://cheese.example.com/v2/cheeses?limit=20&sort=name', {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_TOKEN',
  },
});

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

### Python

```python
import requests

response = requests.get(
    'https://cheese.example.com/v2/cheeses?limit=20&sort=name',
    headers={
        'X-API-Key': 'YOUR_TOKEN',
    },
)
print(response.text)
```

### Go

```go
package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("GET", "https://cheese.example.com/v2/cheeses?limit=20&sort=name", nil)
  req.Header.Set("X-API-Key", "YOUR_TOKEN")
  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()
  data, _ := io.ReadAll(resp.Body)
  fmt.Println(string(data))
}
```

### Rust

```rust
use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    let response = client.get("https://cheese.example.com/v2/cheeses?limit=20&sort=name")
        .header("X-API-Key", "YOUR_TOKEN")
        .send()
        .await?
        .text()
        .await?;
    println!("{}", response);
    Ok(())
}
```