# Get artists

Source: https://docs.recoupable.dev/api-reference/artists/list

Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token.

## GET /api/artists

Full OpenAPI specification: https://docs.recoupable.dev/spec/releases.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://docs.recoupable.dev/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Releases",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/artists": {
      "get": {
        "operationId": "getArtists",
        "description": "Retrieve artists accessible to the authenticated account. The account is derived from the API key or Bearer token. When org_id is omitted, returns only the account's own artists. Pass org_id to view artists in a specific organization. Pass account_id to filter to a specific account the API key has access to.",
        "parameters": [
          {
            "name": "account_id",
            "in": "query",
            "description": "Filter to a specific account's artists. Only applicable when the authenticated account has access to multiple accounts via organization membership.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "org_id",
            "in": "query",
            "description": "Filter to artists in a specific organization. When omitted, returns only personal (non-organization) artists.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Artists retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtistsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArtistsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid authentication"
          },
          "403": {
            "description": "Forbidden - account_id is not accessible with the provided credentials"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ArtistsResponse": {
        "type": "object",
        "required": [
          "status",
          "artists"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ],
            "description": "Status of the request"
          },
          "artists": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Artist"
            },
            "description": "List of artist objects"
          },
          "message": {
            "type": "string",
            "description": "Error message (only present if status is error)"
          }
        }
      },
      "ArtistsErrorResponse": {
        "type": "object",
        "required": [
          "status",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "description": "Status of the request"
          },
          "message": {
            "type": "string",
            "description": "Error message describing what went wrong"
          }
        }
      },
      "Artist": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the artist account. Equal to account_id; use this (or account_id) for /api/artists/{id}/* sub-resources."
          },
          "account_id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the artist account"
          },
          "name": {
            "type": "string",
            "description": "Artist display name"
          },
          "image": {
            "type": "string",
            "nullable": true,
            "description": "Artist profile image URL"
          },
          "instruction": {
            "type": "string",
            "nullable": true,
            "description": "Artist-specific agent instruction / system prompt"
          },
          "knowledges": {
            "type": "array",
            "description": "Artist knowledge-base entries",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          },
          "label": {
            "type": "string",
            "nullable": true,
            "description": "Artist label / category"
          },
          "pinned": {
            "type": "boolean",
            "description": "Whether the account has pinned this artist"
          },
          "account_socials": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ArtistSocial"
            },
            "description": "Existing social media profiles linked to the artist. Missing joined profile records are omitted. A profile with an empty URL is retained with link \"\" and type \"NONE\"."
          }
        }
      },
      "ArtistSocial": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the social profile"
          },
          "username": {
            "type": "string",
            "description": "Username on the platform"
          },
          "profile_url": {
            "type": "string",
            "description": "Full URL to the social media profile"
          },
          "link": {
            "type": "string",
            "description": "Profile URL mirrored from profile_url; an empty URL remains an empty string."
          },
          "type": {
            "type": "string",
            "description": "Uppercase platform identifier inferred from the profile URL, for example INSTAGRAM or LINKEDIN. Unrecognized or empty URLs produce NONE."
          }
        },
        "example": {
          "id": "11111111-1111-4111-8111-111111111111",
          "username": "river",
          "profile_url": "https://instagram.com/river",
          "link": "https://instagram.com/river",
          "type": "INSTAGRAM"
        }
      }
    }
  }
}
```