Skip to content

docs(artists): POST /api/artists resolve-or-create by spotify_artist_id (chat#1889 row 8) #278

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sweetmantech merged 2 commits into from
Jul 29, 2026
Merged

docs(artists): POST /api/artists resolve-or-create by spotify_artist_id (chat#1889 row 8) #278

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d097cb
docs(artists): POST /api/artists resolves-or-creates the canonical fo…
sweetmantech Jul 29, 2026
135ee36
docs(artists): drop em dashes from the endpoint description (customer…
sweetmantech Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion api-reference/openapi/releases.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -554,7 +554,7 @@
}
},
"post": {
"description": "Create a new artist account. The artist can optionally be linked to an organization.",
"description": "Create a new artist account. When spotify_artist_id is provided and a canonical artist already exists for it, the existing artist is linked to the account instead of creating a duplicate. The artist can optionally be linked to an organization.",
"requestBody": {
"description": "Artist creation parameters",
"required": true,
Expand All @@ -567,6 +567,16 @@
}
},
"responses": {
"200": {

@cubic-dev-ai cubic-dev-ai Bot Jul 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The new 200 response for the resolve-or-create flow reuses CreateArtistResponse, but the underlying account_socials array lacks an items schema, so generated clients won't get a typed shape for the server-attached Spotify profile. Consider typing the social entries so both the resolve and create paths accurately expose the response shape.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/releases.json, line 570:

<comment>The new 200 response for the resolve-or-create flow reuses CreateArtistResponse, but the underlying account_socials array lacks an items schema, so generated clients won't get a typed shape for the server-attached Spotify profile. Consider typing the social entries so both the resolve and create paths accurately expose the response shape.</comment>

<file context>
@@ -567,6 +567,16 @@
           }
         },
         "responses": {
+          "200": {
+            "description": "Existing canonical artist for the given spotify_artist_id linked to the account (no new artist created)",
+            "content": {
</file context>

"description": "Existing canonical artist for the given spotify_artist_id linked to the account (no new artist created)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateArtistResponse"
}
}
}
},
Comment on lines +570 to +579

@coderabbitai coderabbitai Bot Jul 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Use a typed, neutral artist response schema.

CreateArtistResponse resolves to CreatedArtist, whose account_socials array has no items schema. The new 200/201 contract therefore does not expose the shape of the server-attached Spotify profile to generated clients. Type the social entries and use a schema that accurately covers both existing and newly created artists.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/openapi/releases.json` around lines 570 - 579, Update the 200
response schema in the release OpenAPI definition to use the neutral artist
response schema covering both existing and newly created artists, rather than
CreateArtistResponse. Ensure the referenced artist schema defines
account_socials with a typed items schema that represents the attached Spotify
profile.

"201": {
"description": "Artist created successfully",
"content": {
Expand Down Expand Up @@ -2822,6 +2832,10 @@
"minLength": 1,
"description": "The name of the artist to create"
},
"spotify_artist_id": {

@cubic-dev-ai cubic-dev-ai Bot Jul 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: spotify_artist_id has no minLength constraint, so "spotify_artist_id": "" would still validate against the schema even though invalid IDs are documented to return 400 elsewhere. Add minLength: 1 if empty strings should be rejected, or update the description to clarify that empty values are accepted.

Prompt for AI agents 
Check if this issue is valid — if so, understand the root cause and fix it. At api-reference/openapi/releases.json, line 2835:

<comment>spotify_artist_id has no minLength constraint, so "spotify_artist_id": "" would still validate against the schema even though invalid IDs are documented to return 400 elsewhere. Add minLength: 1 if empty strings should be rejected, or update the description to clarify that empty values are accepted.</comment>

<file context>
@@ -2822,6 +2832,10 @@
             "minLength": 1,
             "description": "The name of the artist to create"
           },
+          "spotify_artist_id": {
+            "type": "string",
+            "description": "Optional Spotify artist id. When provided, the endpoint resolves-or-creates the canonical artist for that id: if an artist already carries it, that artist is linked to the account and returned (200) instead of creating a duplicate; otherwise the artist is created with its Spotify profile attached (201)."
</file context>

"type": "string",
"description": "Optional Spotify artist id. When provided, the endpoint resolves-or-creates the canonical artist for that id: if an artist already carries it, that artist is linked to the account and returned (200) instead of creating a duplicate; otherwise the artist is created with its Spotify profile attached (201)."
},
Comment on lines +2835 to +2838

@coderabbitai coderabbitai Bot Jul 29, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
rg -n -C5 '\bspotify_artist_id\b' . \
  -g '!api-reference/openapi/releases.json'

Repository: recoupable/docs

Length of output: 153

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf 'Files with spotify_artist_id:\n'
rg -n -C3 '\bspotify_artist_id\b' . || true

printf '\nRelevant OpenAPI section:\n'
sed -n '2828,2842p' api-reference/openapi/releases.json

printf '\nRepo file count and type evidence:\n'
git ls-files | wc -l
git ls-files | sed -n '1,120p'

Repository: recoupable/docs

Length of output: 8846

Clarify and constrain the optional Spotify artist ID.

spotify_artist_id is optional but unminlengthed, so "spotify_artist_id": "" still matches the schema even though any provided value is described as a Spotify identifier and "invalid" IDs return 400 in nearby response docs. Add minLength: 1 if empty IDs are rejected, or update the description/validation wording if empty IDs are accepted.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@api-reference/openapi/releases.json` around lines 2835 - 2838, Constrain the
optional spotify_artist_id property to reject explicitly provided empty strings
by adding a minimum length of 1 while keeping the field optional. Preserve the
existing description and endpoint behavior for valid Spotify identifiers and
omitted values.

"account_id": {
"type": "string",
"format": "uuid",
Expand Down