Confirm Professional Roster Addition

{
  "summary": "Confirm professional roster addition",
  "description": "Requires explicit operator identity confirmation and organization roster intent. Use new only after confirming a distinct professional, including resolving same-name candidates; never infer identity from a name. Use existing with a professional_id from this organization to add roles without renaming. Both songwriter and producer can belong to one record. This operation creates no login account, shared canonical identity, catalog rights, enrichment job, or cross-workspace context. Research/name intake alone never calls this operation. Membership is rechecked before idempotency replay. Legacy MCP equivalent (API key or Privy token): confirm_professional_roster. Not exposed through delegated OAuth MCP. Returns the original saved response on retry, including its created flag and original status (201 for a new record, 200 for an existing record).",
  "security": [
    {
      "bearerAuth": []
    },
    {
      "apiKeyAuth": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "organization_id": {
              "type": "string",
              "format": "uuid"
            },
            "idempotency_key": {
              "type": "string",
              "format": "uuid",
              "description": "Generate once per deliberate operation. Persist and reuse after a timeout or lost response. Scoped to the organization and actor. Different input with the same key is rejected."
            },
            "mode": {
              "type": "string",
              "enum": [
                "new",
                "existing"
              ]
            },
            "name": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            },
            "professional_id": {
              "type": "string",
              "format": "uuid"
            },
            "roles": {
              "type": "array",
              "minItems": 1,
              "maxItems": 2,
              "items": {
                "type": "string",
                "enum": [
                  "songwriter",
                  "producer"
                ]
              }
            },
            "confirmed": {
              "type": "boolean",
              "enum": [
                true
              ]
            },
            "roster_intent": {
              "type": "string",
              "enum": [
                "add"
              ]
            }
          },
          "required": [
            "organization_id",
            "idempotency_key",
            "mode",
            "roles",
            "confirmed",
            "roster_intent"
          ],
          "oneOf": [
            {
              "properties": {
                "mode": {
                  "enum": [
                    "new"
                  ]
                }
              },
              "required": [
                "name"
              ],
              "not": {
                "required": [
                  "professional_id"
                ]
              }
            },
            {
              "properties": {
                "mode": {
                  "enum": [
                    "existing"
                  ]
                }
              },
              "required": [
                "professional_id"
              ],
              "not": {
                "required": [
                  "name"
                ]
              }
            }
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Existing professional roles saved, or replayed existing-record operation",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "professional",
              "created"
            ],
            "properties": {
              "professional": {
                "$ref": "#/components/schemas/OrganizationProfessional"
              },
              "created": {
                "type": "boolean"
              }
            }
          }
        }
      }
    },
    "201": {
      "description": "New professional saved, or replayed new-record operation",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "professional",
              "created"
            ],
            "properties": {
              "professional": {
                "$ref": "#/components/schemas/OrganizationProfessional"
              },
              "created": {
                "type": "boolean"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid or unconfirmed request",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Authentication required",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "Organization access denied, revoked, or record outside this organization",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "409": {
      "description": "Request key already used for different input or actor",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "503": {
      "description": "Unavailable storage or unconfirmed response; retry with the same key and input",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}