# Get all artists

`GET /api/v1/artists`

Get a list of all legendary Argentine Rock artists and explore their contributions to the music scene. You can get one using the [Get an artist](/example/operations/getArtist.md) endpoint.

## Servers

- `https://localhost:3000`
- `https://stoplight.io/mocks/enzonotario/argentine-rock/122547792`

## Parameters

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer<int64>` | No | The number of items to return. Default: `10`. Example: `10`. |
| `offset` | `integer<int64>` | No | The number of items to skip before starting to collect the result set. Default: `0`. Example: `1`. |

## Responses

### 200

Success Response

The request was successful and returns a list of artists.

Response Format

The response includes:
- A `data` array containing artist objects
- Pagination information

> **Note:** You can use the pagination parameters to navigate through large result sets.

Content type: `application/json`

A wrapper for paginated API responses that includes both the data and pagination metadata

Type: `object`.

- `data` (`array<object>`)
  - `id` (`integer<int64>`, required): Unique identifier for the artist in the database. Used in API requests to reference this specific artist. Example: `1`.
  - `name` (`string`, required): Full artistic name of the musician as they are known in the Argentine rock scene. Example: `Charly García`.
  - `description` (`string | null`): Biographical information about the artist and their contribution to Argentine rock music. This field supports Markdown formatting for rich text presentation.

    Example markdown features:
    - *Italic text* for emphasis
    - **Bold text** for strong emphasis
    - Links to [external resources](https://example.com)
    - Bullet points for listing achievements

    Example: `One of the most influential rock musicians in Argentine history.`.
  - `image` (`string | null`): URL to the artist's profile photo or official image. Should be a high-quality image suitable for display in the UI. Example: `https://cdn.rock-legends.com/photos/charly.jpg`.
  - `band` (`string`): Primary musical group or band associated with this artist. Many artists have been part of multiple bands throughout their career, but this field typically contains their most notable affiliation. Example: `Sui Generis`.
- `meta` (`object`): Metadata about the pagination state and available navigation options
  - `limit` (`integer<int64>`): Maximum number of items returned in this response. This value matches the `limit` parameter in the request, or the default value if not specified. Example: `10`.
  - `offset` (`integer<int64>`): Starting position of the items returned, relative to the complete dataset. Used for pagination through large result sets. Example: `0`.
  - `total` (`integer<int64>`): Total number of items available in the complete dataset. Use this to calculate the total number of pages needed for pagination. Example: `100`.
  - `next` (`string | null`): URL path for the next page of results. This is a relative path that can be appended to the API base URL.

    *This field will be `null` when there are no more pages available.*

    Example usage:
    ```javascript
    if (response.meta.next) {
      fetchNextPage(baseUrl + response.meta.next);
    }
    ```

    Example: `/artists?limit=10&offset=10`.

Example:

```json
{
  "data": [
    {
      "id": 1,
      "name": "Charly García",
      "description": "One of the most influential rock musicians in Argentine history.",
      "image": "https://cdn.rock-legends.com/photos/charly.jpg",
      "band": "Sui Generis"
    }
  ],
  "meta": {
    "limit": 10,
    "offset": 0,
    "total": 100,
    "next": "/artists?limit=10&offset=10"
  }
}
```

## Code samples

**cURL**

```bash
curl 'https://localhost:3000/api/v1/artists?limit=10&offset=1'
```

## OpenAPI

Machine-readable specification: [/openapi.json](/openapi.json)
