API REFERENCE

Pin Artist

On this page

POST/api/artists/{id}/pin

Pin an artist. This updates the caller's pinned preference for the artist.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/artists/YOUR_ID/pin' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

idstringrequired

Artist ID.

Responses

200Artist pinned.

application/json

successbooleanrequired

Whether the request succeeded

artistIdstringrequired

The artist ID

format: uuid

pinnedbooleanrequired

The current pinned state

400Bad request - invalid artist ID path parameter

application/json

statusstring · enumrequired

Status of the request

Values: "error"

missing_fieldsarray<string>

List of missing or invalid field names

Item properties

string

errorstringrequired

Error message describing what went wrong

401Unauthorized - missing or invalid authentication

No response body schema is specified.

403Forbidden - the authenticated account cannot access this artist

application/json

statusstring · enumrequired

Status of the request

Values: "error"

missing_fieldsarray<string>

List of missing or invalid field names

Item properties

string

errorstringrequired

Error message describing what went wrong

404Artist not found

application/json

statusstring · enumrequired

Status of the request

Values: "error"

missing_fieldsarray<string>

List of missing or invalid field names

Item properties

string

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download releases.json

View operation source

json

{
  "description": "Pin an artist. This updates the caller's pinned preference for the artist.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "Artist ID.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Artist pinned.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PinArtistResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - invalid artist ID path parameter",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PinArtistErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - missing or invalid authentication"
    },
    "403": {
      "description": "Forbidden - the authenticated account cannot access this artist",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PinArtistErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "Artist not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/PinArtistErrorResponse"
          }
        }
      }
    }
  }
}