RecoupGet a free auditFree audit

API REFERENCE

Get Artists

On this page
GET/api/artists

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.

Authentication

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

Request

cURL
curl --request GET \
  --url 'https://api.recoupable.dev/api/artists' \
  --header 'x-api-key: YOUR_API_KEY'

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

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request GET \
  --url 'https://recoup-api.vercel.app/api/artists'

Parameters

Query parameters

account_idstring

Filter to a specific account's artists. Only applicable when the authenticated account has access to multiple accounts via organization membership.

org_idstring

Filter to artists in a specific organization. When omitted, returns only personal (non-organization) artists.

Responses

200Artists retrieved successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success", "error"

artistsarray<Artist>required

List of artist objects

Item properties for artists
idstring

UUID of the artist account. Equal to account_id; use this (or account_id) for /api/artists/{id}/* sub-resources.

format: uuid

account_idstring

UUID of the artist account

format: uuid

namestring

Artist display name

imagestringnullable

Artist profile image URL

instructionstringnullable

Artist-specific agent instruction / system prompt

knowledgesarray<object>

Artist knowledge-base entries

Item properties for knowledges
namestring
urlstring
typestring
labelstringnullable

Artist label / category

pinnedboolean

Whether the account has pinned this artist

account_socialsarray<ArtistSocial>

Social media profiles linked to the artist (embedded in the /api/artists response)

Item properties for account_socials
idstring

UUID of the social profile

format: uuid

platformstring

Social media platform (e.g., instagram, twitter, tiktok)

usernamestring

Username on the platform

profile_urlstring

Full URL to the social media profile

messagestring

Error message (only present if status is error)

400Bad request - invalid parameters

application/json

statusstring · enumrequired

Status of the request

Values: "error"

messagestringrequired

Error message describing what went wrong

401Unauthorized - missing or invalid authentication

No response body schema is specified.

403Forbidden - account_id is not accessible with the provided credentials

No response body schema is specified.

Full specification

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

Download releases.json
View operation source
json
{
  "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"
    }
  }
}