# Artists

Everything about `Argentine Rock artists` and their contributions to music history.

> **Note:** You will need to authenticate yourself to access some of these endpoints using the [Authenticate a user](/example/operations/loginUser.md) endpoint.

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