docs(artists): POST /api/artists resolve-or-create by spotify_artist_id (chat#1889 row 8) - #278
Conversation
…r a spotify_artist_id Optional spotify_artist_id on CreateArtistRequest: when a canonical artist already carries the id the endpoint links it to the account and returns 200; otherwise it creates with the Spotify profile attached (201). Contract for the dedup-at-creation slice on chat#1889 rows 8-10: one canonical artist per Spotify id, enforced where rows are born. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
📝 WalkthroughWalkthroughThe OpenAPI specification documents optional ChangesArtist API contract
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with 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.
Inline comments:
In `@api-reference/openapi/releases.json`:
- Around line 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.
- Line 557: Clarify the endpoint description for the existing-artist resolution
path: explicitly state whether CreateArtistRequest.organization_id is applied
to, ignored for, or rejected when a canonical artist is returned, while
preserving the documented behavior for newly created artists.
- Around line 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 7620f8f4-e814-43a7-8881-8441f89e2be0
📒 Files selected for processing (1)
api-reference/openapi/releases.json
| }, | ||
| "post": { | ||
| "description": "Create a new artist account. The artist can optionally be linked to an organization.", | ||
| "description": "Create a new artist account, or — when spotify_artist_id is provided and a canonical artist already exists for it — link that existing artist to the account instead of creating a duplicate. The artist can optionally be linked to an organization.", |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Clarify organization_id for the resolve path.
This description implies organization linkage applies to any returned artist, while CreateArtistRequest.organization_id says it links the new artist. Document whether organization linkage is applied, ignored, or rejected when an existing canonical artist is resolved.
🤖 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` at line 557, Clarify the endpoint
description for the existing-artist resolution path: explicitly state whether
CreateArtistRequest.organization_id is applied to, ignored for, or rejected when
a canonical artist is returned, while preserving the documented behavior for
newly created artists.
| "200": { | ||
| "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" | ||
| } | ||
| } | ||
| } | ||
| }, |
There was a problem hiding this comment.
🗄️ 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.
| "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)." | ||
| }, |
There was a problem hiding this comment.
🎯 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.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 1 file
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="api-reference/openapi/releases.json">
<violation number="1" location="api-reference/openapi/releases.json:570">
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.</violation>
<violation number="2" location="api-reference/openapi/releases.json:2835">
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.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| "minLength": 1, | ||
| "description": "The name of the artist to create" | ||
| }, | ||
| "spotify_artist_id": { |
There was a problem hiding this comment.
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>
| } | ||
| }, | ||
| "responses": { | ||
| "200": { |
There was a problem hiding this comment.
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>
…-facing copy rule)
Local render verification — Mintlify dev, all three changes confirmedChecked out this branch locally and rendered it with
Endpoint description (top of page):
The new param, in place in the body schema:
The 200 response, selected in the Response section:
Fixed during verification
Contract ↔ implementation checkThe rendered contract matches api#793 exactly: same JSON re-validated ( |
1 participant
Contract-first PR for chat#1889 row 8 (dedup at creation).
POST /api/artistsgains optionalspotify_artist_id:{ artist }200Merge order: this PR → api#TBD → chat#TBD. The 2026-07-29 decision on the issue: one canonical artist per Spotify id, enforced at creation; no account-scoped canonical lookups (api#792 closed unmerged).
Edited via anchored text edits (
releases.jsondoesn't round-trip byte-identical); re-validated the JSON parses and both the property and the 200 response resolve.🤖 Generated with Claude Code
Summary by cubic
Adds resolve-or-create behavior to
POST /api/artistsusing an optionalspotify_artist_idto prevent duplicate artists and link accounts to the canonical record. OpenAPI now documents 200 on linking existing and 201 on creating a new artist, with copy updated to follow customer-facing style.spotify_artist_idon create.{ artist }.spotify_artist_idkeeps existing create behavior (201).Written for commit 135ee36. Summary will update on new commits.
Summary by CodeRabbit