# Argentine Rock Legends

> The Argentine Rock Legends is an example OpenAPI specification to test OpenAPI tools and libraries. Get all the data for all artists. Inspired by Scalar Galaxy Resources https://github.com/enzonotario/vitepress-openapi https://github.com/OAI/OpenAPI-Specification Markdown Support All descriptions…

---

# 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)

---

# Add a new artist

`POST /api/v1/artists`

Add a new legendary Argentine Rock artist. Make sure they truly deserve the title! You can view it later using the [Get an artist](/example/operations/getArtist.md) endpoint.

## Servers

- `https://stoplight.io/mocks/enzonotario/argentine-rock/122547792`: Mock Server

## Authorization

Use one of the following options:

- Option 1:
  - `bearerAuth`: HTTP bearer. Send `Authorization: Bearer <token>`.
- Option 2:
  - `apiKeyHeader`: API key in header `X-API-Key`.

## Request body

Optional. Artist data

Content type: `application/json`

Represents a legendary Argentine rock musician or performer with their biographical information and associated metadata

Type: `object` (schema `Artist`).

- `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`.

Example (Charly):

```json
{
  "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"
}
```

Example (Maria):

```json
{
  "name": "Maria Gabriela Epumer",
  "description": "A very important rock musician in Argentine history.",
  "image": "https://cdn.rock-legends.com/photos/maria.jpg",
  "band": "Viudas e Hijas de Roque Enroll"
}
```

## Responses

### 201

Artist Created Successfully

The artist has been successfully added to our database.

Response Details

The response includes the complete artist object with:
- A newly assigned unique `id`
- All the information you provided in the request

Content type: `application/json`

Represents a legendary Argentine rock musician or performer with their biographical information and associated metadata

Type: `object` (see schema `Artist` above).

Example (Charly):

```json
{
  "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"
}
```

Example (Maria):

```json
{
  "id": 2,
  "name": "Maria Gabriela Epumer",
  "description": "A very important rock musician in Argentine history.",
  "image": "https://cdn.rock-legends.com/photos/maria.jpg",
  "band": "Viudas e Hijas de Roque Enroll"
}
```

### 400

Bad Request

The server could not process your request due to invalid input.

Common Causes

- Missing required fields
- Invalid data format
- Validation errors

> **Tip:** Check the error message in the response for specific details about what went wrong.

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (schema `Error`).

- `type` (`string`): A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem. Example: `https://example.com/errors/generic-error`.
- `title` (`string`): Short, human-readable summary of the problem. This should not change from occurrence to occurrence of the same problem type. Example: `Something went wrong here.`.
- `status` (`integer<int64>`): HTTP status code generated by the origin server for this occurrence of the problem. This will match the status code in the actual HTTP response. Example: `403`.
- `detail` (`string`): Human-readable explanation specific to this occurrence of the problem. This field can contain:

  - Detailed error information
  - Suggestions for resolution
  - Links to support resources

  Developers should use this information to understand what went wrong and how to fix it.

  Example: `Unfortunately, we can’t provide further information.`.

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

### 403

Forbidden

You don't have permission to create this resource.

Possible Reasons

- Your API key doesn't have write permissions
- You've reached your quota limit
- The resource is protected

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (see schema `Error` above).

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

## Code samples

**cURL**

```bash
curl https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/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"
}'
```

## OpenAPI

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

---

# Get an artist

`GET /api/v1/artists/{artistId}`

Learn more about a specific Argentine Rock artist and their legacy. You can update it using the [Update an artist](/example/operations/updateArtist.md) endpoint.

## Servers

- `https://stoplight.io/mocks/enzonotario/argentine-rock/122547792`: Mock Server

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `artistId` | `integer<int64>` | Yes | Example: `1`. |

## Responses

### 200

Artist Found

The requested artist was found and returned successfully.

Response Format

The response includes the complete artist object with all available details:

- `id`: Unique identifier for the artist
- `name`: Full name of the artist
- `description`: Biographical information
- `image`: URL to the artist's photo
- `band`: Primary band association

Content type: `application/json`

Represents a legendary Argentine rock musician or performer with their biographical information and associated metadata

Type: `object` (schema `Artist`).

- `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`.

Example:

```json
{
  "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"
}
```

### 404

Artist Not Found

The requested artist could not be found in our database.

Possible Reasons

- The artist ID doesn't exist
- The artist has been removed
- You've entered an incorrect ID

> **Tip:** Double-check the artist ID and try again. You can get a list of all available artists using the [Get all artists](/example/operations/getAllArtists.md) endpoint.

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (schema `Error`).

- `type` (`string`): A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem. Example: `https://example.com/errors/generic-error`.
- `title` (`string`): Short, human-readable summary of the problem. This should not change from occurrence to occurrence of the same problem type. Example: `Something went wrong here.`.
- `status` (`integer<int64>`): HTTP status code generated by the origin server for this occurrence of the problem. This will match the status code in the actual HTTP response. Example: `403`.
- `detail` (`string`): Human-readable explanation specific to this occurrence of the problem. This field can contain:

  - Detailed error information
  - Suggestions for resolution
  - Links to support resources

  Developers should use this information to understand what went wrong and how to fix it.

  Example: `Unfortunately, we can’t provide further information.`.

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

## Code samples

**cURL**

```bash
curl https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1
```

## OpenAPI

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

---

# Update an artist

`PUT /api/v1/artists/{artistId}`

Update the information of a legendary Argentine Rock artist. Make sure to provide accurate data. You can get the current data using the [Get an artist](/example/operations/getArtist.md) endpoint.

## Servers

- `https://stoplight.io/mocks/enzonotario/argentine-rock/122547792`: Mock Server

## Authorization

Use one of the following options:

- Option 1:
  - `bearerAuth`: HTTP bearer. Send `Authorization: Bearer <token>`.
- Option 2:
  - `apiKeyHeader`: API key in header `X-API-Key`.

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `artistId` | `integer<int64>` | Yes | Example: `1`. |

## Request body

Optional. Artist data

Content type: `application/json`

Represents a legendary Argentine rock musician or performer with their biographical information and associated metadata

Type: `object` (schema `Artist`).

- `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`.

Example:

```json
{
  "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"
}
```

## Responses

### 200

Artist Updated Successfully

The artist information has been successfully updated in our database.

Response Details

The response includes the complete updated artist object with all the changes you made.

> **Note:** All fields are returned in the response, even if you only updated some of them.

Content type: `application/json`

Represents a legendary Argentine rock musician or performer with their biographical information and associated metadata

Type: `object` (see schema `Artist` above).

Example:

```json
{
  "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"
}
```

### 400

Bad Request

The server could not process your update request due to invalid input.

Common Causes

- Missing required fields
- Invalid data format
- Validation errors

> **Tip:** Check the error message in the response for specific details about what went wrong.

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (schema `Error`).

- `type` (`string`): A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem. Example: `https://example.com/errors/generic-error`.
- `title` (`string`): Short, human-readable summary of the problem. This should not change from occurrence to occurrence of the same problem type. Example: `Something went wrong here.`.
- `status` (`integer<int64>`): HTTP status code generated by the origin server for this occurrence of the problem. This will match the status code in the actual HTTP response. Example: `403`.
- `detail` (`string`): Human-readable explanation specific to this occurrence of the problem. This field can contain:

  - Detailed error information
  - Suggestions for resolution
  - Links to support resources

  Developers should use this information to understand what went wrong and how to fix it.

  Example: `Unfortunately, we can’t provide further information.`.

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

### 403

Forbidden

You don't have permission to update this artist.

Possible Reasons

- Your API key doesn't have write permissions
- You're trying to update a protected artist record
- You've reached your quota limit

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (see schema `Error` above).

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

## Code samples

**cURL**

```bash
curl https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1 \
  --request PUT \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/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"
}'
```

## OpenAPI

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

---

# Delete an artist

`DELETE /api/v1/artists/{artistId}`

> **Deprecated:** this operation is deprecated and may be removed in a future version.

This endpoint was used to delete artists. Unfortunately, that caused a lot of controversy. So, this endpoint is now deprecated and should not be used anymore. You can use the [Update an artist](/example/operations/updateArtist.md) endpoint instead.

## Servers

- `https://stoplight.io/mocks/enzonotario/argentine-rock/122547792`: Mock Server

## Authorization

Use one of the following options:

- Option 1:
  - `bearerAuth`: HTTP bearer. Send `Authorization: Bearer <token>`.
- Option 2:
  - `apiKeyHeader`: API key in header `X-API-Key`.

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `artistId` | `integer<int64>` | Yes | Example: `1`. |

## Responses

### 400

Bad Request - Deprecated Endpoint

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (schema `Error`).

- `type` (`string`): A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem. Example: `https://example.com/errors/generic-error`.
- `title` (`string`): Short, human-readable summary of the problem. This should not change from occurrence to occurrence of the same problem type. Example: `Something went wrong here.`.
- `status` (`integer<int64>`): HTTP status code generated by the origin server for this occurrence of the problem. This will match the status code in the actual HTTP response. Example: `403`.
- `detail` (`string`): Human-readable explanation specific to this occurrence of the problem. This field can contain:

  - Detailed error information
  - Suggestions for resolution
  - Links to support resources

  Developers should use this information to understand what went wrong and how to fix it.

  Example: `Unfortunately, we can’t provide further information.`.

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

### 403

Forbidden - Deprecated Endpoint

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (see schema `Error` above).

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

## Code samples

**cURL**

```bash
curl https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1 \
  --request DELETE \
  --header 'Authorization: Bearer <token>'
```

## OpenAPI

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

---

# Get all albums

`GET /api/v1/artists/{artistId}/albums`

Get a list of all albums from a legendary Argentine Rock artist. You can add a new album using the [Add a new album](/example/operations/createAlbum.md) endpoint.

## Servers

- `https://stoplight.io/mocks/enzonotario/argentine-rock/122547792`: Mock Server

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `artistId` | `integer<int64>` | Yes | Example: `1`. |

### 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

Albums Found

The request was successful and returns a list of albums for the specified artist.

Response Format

The response includes:
- A `data` array containing album objects
- Pagination information for navigating through large collections

> **Note:** If the artist has no albums, the data array will be empty but the request will still return a 200 status code.

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 album. Example: `1`.
  - `name` (`string`, required): Official title of the album as released in Argentina. Example: `La Máquina de Hacer Pájaros`.
  - `year` (`integer<int64>`): Year when the album was first released. For remastered or re-released albums, this refers to the original release date. Example: `1976`.
  - `image` (`string | null`): URL to the album cover artwork. The image should be a square format, typically showing the original album cover design. Example: `https://cdn.rock-legends.com/photos/la-maquina.jpg`.
- `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": "La Máquina de Hacer Pájaros",
      "year": 1976,
      "image": "https://cdn.rock-legends.com/photos/la-maquina.jpg"
    }
  ],
  "meta": {
    "limit": 10,
    "offset": 0,
    "total": 100,
    "next": "/artists?limit=10&offset=10"
  }
}
```

## Code samples

**cURL**

```bash
curl 'https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums?limit=10&offset=1'
```

## OpenAPI

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

---

# Add a new album

`POST /api/v1/artists/{artistId}/albums`

Add a new album to a legendary Argentine Rock artist. Make sure it's a masterpiece! You can view all albums using the [Get all albums](/example/operations/getAllAlbums.md) endpoint.

## Servers

- `https://stoplight.io/mocks/enzonotario/argentine-rock/122547792`: Mock Server

## Authorization

Use one of the following options:

- Option 1:
  - `bearerAuth`: HTTP bearer. Send `Authorization: Bearer <token>`.
- Option 2:
  - `apiKeyHeader`: API key in header `X-API-Key`.

## Parameters

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `artistId` | `integer<int64>` | Yes | Example: `1`. |

## Request body

Optional. Album data

Content type: `application/json`

Represents a music album released by an Argentine rock artist or band

Type: `object` (schema `Album`).

- `id` (`integer<int64>`, required): Unique identifier for the album. Example: `1`.
- `name` (`string`, required): Official title of the album as released in Argentina. Example: `La Máquina de Hacer Pájaros`.
- `year` (`integer<int64>`): Year when the album was first released. For remastered or re-released albums, this refers to the original release date. Example: `1976`.
- `image` (`string | null`): URL to the album cover artwork. The image should be a square format, typically showing the original album cover design. Example: `https://cdn.rock-legends.com/photos/la-maquina.jpg`.

Example:

```json
{
  "id": 1,
  "name": "La Máquina de Hacer Pájaros",
  "year": 1976,
  "image": "https://cdn.rock-legends.com/photos/la-maquina.jpg"
}
```

## Responses

### 201

Album Created Successfully

The album has been successfully added to the artist's discography.

Response Details

The response includes the complete album object with:
- A newly assigned unique `id`
- All the information you provided in the request
- The association with the artist

Content type: `application/json`

Represents a music album released by an Argentine rock artist or band

Type: `object` (see schema `Album` above).

Example:

```json
{
  "id": 1,
  "name": "La Máquina de Hacer Pájaros",
  "year": 1976,
  "image": "https://cdn.rock-legends.com/photos/la-maquina.jpg"
}
```

### 400

Bad Request

The server could not process your request due to invalid album data.

Common Causes

- Missing required fields (title, year)
- Invalid year format (must be a number)
- Year out of valid range

> **Tip:** Make sure the album year is accurate and in the correct format.

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (schema `Error`).

- `type` (`string`): A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem. Example: `https://example.com/errors/generic-error`.
- `title` (`string`): Short, human-readable summary of the problem. This should not change from occurrence to occurrence of the same problem type. Example: `Something went wrong here.`.
- `status` (`integer<int64>`): HTTP status code generated by the origin server for this occurrence of the problem. This will match the status code in the actual HTTP response. Example: `403`.
- `detail` (`string`): Human-readable explanation specific to this occurrence of the problem. This field can contain:

  - Detailed error information
  - Suggestions for resolution
  - Links to support resources

  Developers should use this information to understand what went wrong and how to fix it.

  Example: `Unfortunately, we can’t provide further information.`.

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

### 403

Forbidden

You don't have permission to add albums to this artist.

Possible Reasons

- Your API key doesn't have write permissions
- The artist's discography is locked or protected
- You've reached your quota for album additions

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (see schema `Error` above).

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

## Code samples

**cURL**

```bash
curl https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/artists/1/albums \
  --request POST \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": 1,
  "name": "La Máquina de Hacer Pájaros",
  "year": 1976,
  "image": "https://cdn.rock-legends.com/photos/la-maquina.jpg"
}'
```

## OpenAPI

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

---

# Create a user

`POST /api/v1/user/signup`

Create a user account to access exclusive content about Argentine Rock legends. After signing up, you can access endpoints like [Get all artists](/example/operations/getAllArtists.md) to explore the data.

## Servers

- `https://stoplight.io/mocks/enzonotario/argentine-rock/122547792`: Mock Server

## Request body

Optional.

Content type: `application/json`

Represents a new user registration for the Argentine Rock Legends API

Type: `object` (schema `NewUser`).

- `name` (`string`, required): Full name of the user registering for an account. Example: `Carlos`.
- `email` (`string<email>`, required): Email address that will be used for account identification and communication. Must be a valid email format. Example: `carlos@rock-legends.com`.
- `password` (`string`, required): User's secret password for authentication. *Must be at least 8 characters* and should include a mix of letters, numbers, and special characters for better security. Constraints: minLength: 8. Example: `i-love-rock`.

Example (Carlos):

```json
{
  "name": "Carlos",
  "email": "carlos@rock-legends.com",
  "password": "i-love-rock"
}
```

Example (Maria):

```json
{
  "name": "Maria",
  "email": "maria@rock-legends.com",
  "password": "rock-n-roll"
}
```

## Responses

### 201

User Created Successfully

Your account has been created and you can now access the Argentine Rock Legends API.

Response Details

The response includes your user information (excluding the password) and your API key for authentication.

> **Important:** Save your API key securely as it will be needed for authenticated requests.

Content type: `application/json`

Represents a registered user in the Argentine Rock Legends system with their profile information

Type: `object` (schema `User`).

- `id` (`integer<int64>`, required): Unique identifier for the user account. This value is automatically generated upon registration and cannot be changed. Example: `1`.
- `name` (`string`, required): User's full name as provided during registration. Example: `Carlos`.
- `email` (`string<email>`, required): User's verified email address used for account access and notifications. This serves as the primary contact method for important account updates. Example: `carlos@rock-legends.com`.

Example:

```json
{
  "id": 1,
  "name": "Carlos",
  "email": "carlos@rock-legends.com"
}
```

### 400

Registration Failed

The server could not process your registration request.

Common Causes

- Email address already in use
- Missing required fields
- Password doesn't meet security requirements
- Invalid email format

> **Tip:** Make sure your email is valid and your password is at least 8 characters long.

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (schema `Error`).

- `type` (`string`): A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem. Example: `https://example.com/errors/generic-error`.
- `title` (`string`): Short, human-readable summary of the problem. This should not change from occurrence to occurrence of the same problem type. Example: `Something went wrong here.`.
- `status` (`integer<int64>`): HTTP status code generated by the origin server for this occurrence of the problem. This will match the status code in the actual HTTP response. Example: `403`.
- `detail` (`string`): Human-readable explanation specific to this occurrence of the problem. This field can contain:

  - Detailed error information
  - Suggestions for resolution
  - Links to support resources

  Developers should use this information to understand what went wrong and how to fix it.

  Example: `Unfortunately, we can’t provide further information.`.

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

## Code samples

**cURL**

```bash
curl https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/user/signup \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Carlos",
  "email": "carlos@rock-legends.com",
  "password": "i-love-rock"
}'
```

## OpenAPI

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

---

# Authenticate a user

`POST /api/v1/user/login`

Authenticate with your credentials to access protected endpoints in the Argentine Rock Legends API.

## Servers

- `https://stoplight.io/mocks/enzonotario/argentine-rock/122547792`: Mock Server

## Request body

Optional.

Content type: `application/json`

Type: `object`.

- `email` (`string<email>`, required): Email address used during registration
- `password` (`string`, required): User's password

Example (Carlos):

```json
{
  "email": "carlos@rock-legends.com",
  "password": "i-love-rock"
}
```

## Responses

### 200

Authentication Successful

You have been successfully authenticated.

Response Details

The response includes:
- Your user information
- Authentication tokens (JWT token and API key)
- Token expiration information

> **Important:** Store these credentials securely and include them in subsequent API requests.

Content type: `application/json`

Type: `object`.

- `user` (`object`, schema `User`): Represents a registered user in the Argentine Rock Legends system with their profile information
  - `id` (`integer<int64>`, required): Unique identifier for the user account. This value is automatically generated upon registration and cannot be changed. Example: `1`.
  - `name` (`string`, required): User's full name as provided during registration. Example: `Carlos`.
  - `email` (`string<email>`, required): User's verified email address used for account access and notifications. This serves as the primary contact method for important account updates. Example: `carlos@rock-legends.com`.
- `token` (`string`): JWT token for Bearer authentication
- `api_key` (`string`): API key for X-API-Key header authentication
- `expires_at` (`string<date-time>`): Expiration timestamp for the JWT token

Example (Carlos):

```json
{
  "user": {
    "id": 1,
    "name": "Carlos",
    "email": "carlos@rock-legends.com"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "api_key": "rock-legends-api-key-12345",
  "expires_at": "2025-08-26T19:28:00Z"
}
```

### 400

Bad Request

The server could not process your login request.

Common Causes

- Missing required fields
- Invalid email format

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (schema `Error`).

- `type` (`string`): A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem. Example: `https://example.com/errors/generic-error`.
- `title` (`string`): Short, human-readable summary of the problem. This should not change from occurrence to occurrence of the same problem type. Example: `Something went wrong here.`.
- `status` (`integer<int64>`): HTTP status code generated by the origin server for this occurrence of the problem. This will match the status code in the actual HTTP response. Example: `403`.
- `detail` (`string`): Human-readable explanation specific to this occurrence of the problem. This field can contain:

  - Detailed error information
  - Suggestions for resolution
  - Links to support resources

  Developers should use this information to understand what went wrong and how to fix it.

  Example: `Unfortunately, we can’t provide further information.`.

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

### 401

Authentication Failed

The server could not authenticate you with the provided credentials.

Possible Reasons

- Incorrect email or password
- Account has been locked due to too many failed attempts
- Account has been deactivated

> **Tip:** Double-check your credentials and try again. If you've forgotten your password, use the password reset endpoint.

Content type: `application/json`

Standard error response following [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) for Problem Details in HTTP APIs. This format provides a consistent way to communicate errors across all API endpoints.

Type: `object` (see schema `Error` above).

Example:

```json
{
  "type": "https://example.com/errors/generic-error",
  "title": "Something went wrong here.",
  "status": 403,
  "detail": "Unfortunately, we can’t provide further information."
}
```

## Code samples

**cURL**

```bash
curl https://stoplight.io/mocks/enzonotario/argentine-rock/122547792/api/v1/user/login \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "user@example.com",
  "password": "string"
}'
```

## OpenAPI

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