openapi: 3.0.3
info:
  title: 'Bazaar Spot Backend API Documentation'
  description: ''
  version: 1.0.0
servers:
  - url: 'https://bazaarspot-api.test'
tags:
  - name: Authentication
    description: ''
  - name: Categories
    description: ''
  - name: Collections
    description: ''
  - name: Comments
    description: ''
  - name: Endpoints
    description: ''
  - name: 'Internal Analytics'
    description: ''
  - name: Items
    description: ''
  - name: Notifications
    description: ''
  - name: 'Post Likes'
    description: ''
  - name: Posts
    description: ''
  - name: 'Profile Blocks'
    description: ''
  - name: 'Profile Friend Requests'
    description: ''
  - name: 'Profile Friends'
    description: ''
  - name: Profiles
    description: ''
  - name: Referrals
    description: ''
  - name: Reviews
    description: ''
  - name: Shareables
    description: ''
  - name: Shops
    description: ''
  - name: 'User Bookmarked Items'
    description: ''
  - name: 'User Favorite Shops'
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'Get a bearer token from the `POST /v1/auth/login` endpoint.'
security:
  -
    default: []
paths:
  /v1/auth/register:
    post:
      summary: Register
      operationId: register
      description: 'Create a new account and issue a Sanctum bearer token.'
      parameters: []
      responses:
        201:
          description: 'Registration succeeded.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: users
                    attributes:
                      name: 'Mittie Considine'
                      email: lexus42@example.com
                      email_verified_at: '2026-07-06T10:01:48+00:00'
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                  meta:
                    token: 1|example-token
                    token_type: Bearer
                    expires_at: null
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: users
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Mittie Considine'
                          email:
                            type: string
                            example: lexus42@example.com
                          email_verified_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                  meta:
                    type: object
                    properties:
                      token:
                        type: string
                        example: 1|example-token
                      token_type:
                        type: string
                        example: Bearer
                      expires_at:
                        type: string
                        example: null
                        nullable: true
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                  errors:
                    email:
                      - 'The email has already been taken.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
                  errors:
                    type: object
                    properties:
                      email:
                        type: array
                        example:
                          - 'The email has already been taken.'
                        items:
                          type: string
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Display name for the account.'
                  example: 'Jane Doe'
                email:
                  type: string
                  description: 'Unique email address for login.'
                  example: jane@example.com
                password:
                  type: string
                  description: 'Account password.'
                  example: password123
                device_name:
                  type: string
                  description: 'Client device label for token tracking.'
                  example: ios-app
                profile:
                  type: object
                  description: 'Initial profile attributes.'
                  example: []
                  properties:
                    handle:
                      type: string
                      description: 'Unique initial profile handle.'
                      example: jane_doe
                    display_name:
                      type: string
                      description: 'Initial profile display name.'
                      example: 'Jane Doe'
                    bio:
                      type: string
                      description: 'Initial profile biography.'
                      example: architecto
                      nullable: true
                    avatar_url:
                      type: string
                      description: 'Initial profile avatar URL.'
                      example: 'http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html'
                      nullable: true
                  required:
                    - handle
                referral_code:
                  type: string
                  description: 'Profile referral code. Required when referral-only signup is enabled.'
                  example: AbCdEfGhIjKlMnOpQrStUv
              required:
                - name
                - email
                - password
                - profile
      security: []
  /v1/auth/registration-policy:
    get:
      summary: 'Registration Policy'
      operationId: registrationPolicy
      description: 'Return the current referral requirement for registration.'
      parameters: []
      responses:
        200:
          description: 'Registration policy.'
          content:
            application/json:
              schema:
                type: object
                example:
                  referral_required: false
                properties:
                  referral_required:
                    type: boolean
                    example: false
      tags:
        - Authentication
      security: []
  /v1/auth/login:
    post:
      summary: Login
      operationId: login
      description: 'Authenticate a user and issue a Sanctum bearer token.'
      parameters: []
      responses:
        200:
          description: 'Login succeeded.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: users
                    attributes:
                      name: 'Viva Marquardt'
                      email: hirthe.theo@example.com
                      email_verified_at: '2026-07-06T10:01:48+00:00'
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                  meta:
                    token: 1|example-token
                    token_type: Bearer
                    expires_at: null
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: users
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Viva Marquardt'
                          email:
                            type: string
                            example: hirthe.theo@example.com
                          email_verified_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                  meta:
                    type: object
                    properties:
                      token:
                        type: string
                        example: 1|example-token
                      token_type:
                        type: string
                        example: Bearer
                      expires_at:
                        type: string
                        example: null
                        nullable: true
        422:
          description: 'Credentials were invalid.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                  errors:
                    email:
                      - 'The provided credentials are incorrect.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
                  errors:
                    type: object
                    properties:
                      email:
                        type: array
                        example:
                          - 'The provided credentials are incorrect.'
                        items:
                          type: string
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: 'User email address.'
                  example: jane@example.com
                password:
                  type: string
                  description: 'User password.'
                  example: password123
                device_name:
                  type: string
                  description: 'Client device label for token tracking.'
                  example: ios-app
              required:
                - email
                - password
                - device_name
      security: []
  /v1/auth/password/forgot:
    post:
      summary: 'Request Password Reset'
      operationId: requestPasswordReset
      description: 'Send a password reset link to the provided email if an account exists.'
      parameters: []
      responses:
        200:
          description: 'Password reset request accepted.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'If the account exists, a password reset link has been sent.'
                properties:
                  message:
                    type: string
                    example: 'If the account exists, a password reset link has been sent.'
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: 'Account email address.'
                  example: jane@example.com
              required:
                - email
      security: []
  /v1/auth/password/reset:
    post:
      summary: 'Reset Password'
      operationId: resetPassword
      description: 'Reset the user password using a valid reset token.'
      parameters: []
      responses:
        200:
          description: 'Password reset succeeded.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Your password has been reset.'
                properties:
                  message:
                    type: string
                    example: 'Your password has been reset.'
        422:
          description: 'Reset token or payload was invalid.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                  errors:
                    email:
                      - 'This password reset token is invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
                  errors:
                    type: object
                    properties:
                      email:
                        type: array
                        example:
                          - 'This password reset token is invalid.'
                        items:
                          type: string
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: 'Password reset token.'
                  example: reset-token-value
                email:
                  type: string
                  description: 'Account email associated with token.'
                  example: jane@example.com
                password:
                  type: string
                  description: 'New account password.'
                  example: new-password123
                password_confirmation:
                  type: string
                  description: 'Must match password.'
                  example: new-password123
              required:
                - token
                - email
                - password
                - password_confirmation
      security: []
  '/v1/auth/password/reset/{token}':
    get:
      summary: 'Read Reset Token Payload'
      operationId: readResetTokenPayload
      description: 'Return reset token and email payload for API clients handling email reset links.'
      parameters:
        -
          in: query
          name: email
          description: 'Account email from the reset link.'
          example: jane@example.com
          required: false
          schema:
            type: string
            description: 'Account email from the reset link.'
            example: jane@example.com
      responses:
        200:
          description: 'Reset payload data.'
          content:
            application/json:
              schema:
                type: object
                example:
                  token: reset-token-value
                  email: jane@example.com
                properties:
                  token:
                    type: string
                    example: reset-token-value
                  email:
                    type: string
                    example: jane@example.com
      tags:
        - Authentication
      security: []
    parameters:
      -
        in: path
        name: token
        description: 'Password reset token from reset link.'
        example: reset-token-value
        required: true
        schema:
          type: string
  '/v1/auth/email/verify/{id}/{hash}':
    get:
      summary: 'Verify Email'
      operationId: verifyEmail
      description: 'Verify a user email using the signed verification link parameters.'
      parameters: []
      responses:
        200:
          description: 'Email was verified.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Email verified successfully.'
                properties:
                  message:
                    type: string
                    example: 'Email verified successfully.'
        403:
          description: 'Signed URL was invalid, expired, or mismatched.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Invalid verification link.'
                properties:
                  message:
                    type: string
                    example: 'Invalid verification link.'
      tags:
        - Authentication
      security: []
    parameters:
      -
        in: path
        name: id
        description: 'User ULID from the signed verification link.'
        example: 01HZX3W3T4J8Q57XNZD5BPHJ92
        required: true
        schema:
          type: string
      -
        in: path
        name: hash
        description: 'SHA-1 hash of the email from the signed verification link.'
        example: 8c4f4370e5db9b5be6d0f4c95495f49f998fa32a
        required: true
        schema:
          type: string
  /v1/auth/me:
    get:
      summary: 'Get Current User'
      operationId: getCurrentUser
      description: 'Return the authenticated user for the current bearer token.'
      parameters: []
      responses:
        200:
          description: 'Authenticated user profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: users
                    attributes:
                      name: 'Morgan Hirthe'
                      email: dare.emelie@example.com
                      email_verified_at: '2026-07-06T10:01:48+00:00'
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: users
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Morgan Hirthe'
                          email:
                            type: string
                            example: dare.emelie@example.com
                          email_verified_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Authentication
  /v1/auth/logout:
    post:
      summary: Logout
      operationId: logout
      description: 'Revoke the current Sanctum token.'
      parameters: []
      responses:
        204:
          description: 'Token revoked.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Authentication
  /v1/auth/tokens:
    get:
      summary: 'List Tokens'
      operationId: listTokens
      description: 'List personal access tokens for the authenticated user.'
      parameters: []
      responses:
        200:
          description: 'Token list payload.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: '1'
                      type: personal-access-tokens
                      attributes:
                        name: ios-app
                        abilities:
                          - 'auth:me'
                          - 'auth:logout'
                        last_used_at: null
                        expires_at: '2026-02-24T12:00:00+00:00'
                        created_at: '2026-02-23T12:00:00+00:00'
                        updated_at: '2026-02-23T12:00:00+00:00'
                        is_current: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: '1'
                        type: personal-access-tokens
                        attributes:
                          name: ios-app
                          abilities:
                            - 'auth:me'
                            - 'auth:logout'
                          last_used_at: null
                          expires_at: '2026-02-24T12:00:00+00:00'
                          created_at: '2026-02-23T12:00:00+00:00'
                          updated_at: '2026-02-23T12:00:00+00:00'
                          is_current: true
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: '1'
                        type:
                          type: string
                          example: personal-access-tokens
                        attributes:
                          type: object
                          properties:
                            name:
                              type: string
                              example: ios-app
                            abilities:
                              type: array
                              example:
                                - 'auth:me'
                                - 'auth:logout'
                              items:
                                type: string
                            last_used_at:
                              type: string
                              example: null
                              nullable: true
                            expires_at:
                              type: string
                              example: '2026-02-24T12:00:00+00:00'
                            created_at:
                              type: string
                              example: '2026-02-23T12:00:00+00:00'
                            updated_at:
                              type: string
                              example: '2026-02-23T12:00:00+00:00'
                            is_current:
                              type: boolean
                              example: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - Authentication
    delete:
      summary: 'Revoke All Tokens'
      operationId: revokeAllTokens
      description: 'Revoke all personal access tokens for the authenticated user.'
      parameters: []
      responses:
        204:
          description: 'All tokens revoked.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - Authentication
  '/v1/auth/tokens/{token_id}':
    delete:
      summary: 'Revoke Token'
      operationId: revokeToken
      description: 'Revoke one personal access token owned by the authenticated user.'
      parameters: []
      responses:
        204:
          description: 'Token revoked.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Token does not belong to current user or no longer exists.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Token not found.'
                properties:
                  message:
                    type: string
                    example: 'Token not found.'
      tags:
        - Authentication
    parameters:
      -
        in: path
        name: token_id
        description: 'Personal access token id.'
        example: 42
        required: true
        schema:
          type: integer
  /v1/auth/email/verification-notification:
    post:
      summary: 'Send Verification Email'
      operationId: sendVerificationEmail
      description: 'Send (or resend) an email verification link to the authenticated user.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Verification email queued/sent.'
                    type: object
                    example:
                      message: 'Verification link sent.'
                    properties:
                      message:
                        type: string
                        example: 'Verification link sent.'
                  -
                    description: 'User already verified.'
                    type: object
                    example:
                      message: 'Email is already verified.'
                    properties:
                      message:
                        type: string
                        example: 'Email is already verified.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - Authentication
  /v1/categories:
    get:
      summary: 'List Categories'
      operationId: listCategories
      description: 'List categories ordered for client-side hierarchy rendering.'
      parameters: []
      responses:
        200:
          description: 'Category list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: categories
                      attributes:
                        name: 'Eius Et'
                        slug: eius-et
                        parent_id: null
                        path: eius-et
                        category_level: 1
                        is_last: true
                    -
                      id: ''
                      type: categories
                      attributes:
                        name: 'Animi Quos'
                        slug: animi-quos
                        parent_id: null
                        path: animi-quos
                        category_level: 1
                        is_last: true
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: categories
                        attributes:
                          name: 'Eius Et'
                          slug: eius-et
                          parent_id: null
                          path: eius-et
                          category_level: 1
                          is_last: true
                      -
                        id: ''
                        type: categories
                        attributes:
                          name: 'Animi Quos'
                          slug: animi-quos
                          parent_id: null
                          path: animi-quos
                          category_level: 1
                          is_last: true
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: categories
                        attributes:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'Eius Et'
                            slug:
                              type: string
                              example: eius-et
                            parent_id:
                              type: string
                              example: null
                              nullable: true
                            path:
                              type: string
                              example: eius-et
                            category_level:
                              type: integer
                              example: 1
                            is_last:
                              type: boolean
                              example: true
      tags:
        - Categories
      security: []
  /v1/collections:
    get:
      summary: 'List Collections'
      operationId: listCollections
      description: 'List collections with filtering, sorting, pagination, and optional relationship includes.'
      parameters:
        -
          in: query
          name: 'filter[search]'
          description: 'Search by name, slug, or description.'
          example: summer
          required: false
          schema:
            type: string
            description: 'Search by name, slug, or description.'
            example: summer
        -
          in: query
          name: 'filter[slug]'
          description: 'Filter by exact collection slug.'
          example: summer-picks
          required: false
          schema:
            type: string
            description: 'Filter by exact collection slug.'
            example: summer-picks
        -
          in: query
          name: 'filter[owner_profile_id]'
          description: 'Filter collections owned by this profile ULID.'
          example: 01ktwg1fhzq1dpagvermfbjzad
          required: false
          schema:
            type: string
            description: 'Filter collections owned by this profile ULID.'
            example: 01ktwg1fhzq1dpagvermfbjzad
        -
          in: query
          name: 'filter[shared_with_profile_id]'
          description: 'Filter collections shared with this profile ULID.'
          example: 01ktwg1fhzq1dpagvermfbjzad
          required: false
          schema:
            type: string
            description: 'Filter collections shared with this profile ULID.'
            example: 01ktwg1fhzq1dpagvermfbjzad
        -
          in: query
          name: 'filter[item_id]'
          description: 'Filter collections containing this item ULID.'
          example: 01ktwg1fhzq1dpagvermfbjzad
          required: false
          schema:
            type: string
            description: 'Filter collections containing this item ULID.'
            example: 01ktwg1fhzq1dpagvermfbjzad
        -
          in: query
          name: 'filter[shop_id]'
          description: 'Filter collections containing this shop ULID.'
          example: 01ktwg1fhzq1dpagvermfbjzad
          required: false
          schema:
            type: string
            description: 'Filter collections containing this shop ULID.'
            example: 01ktwg1fhzq1dpagvermfbjzad
        -
          in: query
          name: 'filter[visibility]'
          description: 'Filter by collection visibility.'
          example: Public
          required: false
          schema:
            type: string
            description: 'Filter by collection visibility.'
            example: Public
            enum:
              - 'Only me'
              - Friends
              - Followers
              - 'Friends of Friends'
              - Public
        -
          in: query
          name: 'filter[contents]'
          description: 'Comma-separated contents to match with OR semantics.'
          example: 'items,shops'
          required: false
          schema:
            type: string
            description: 'Comma-separated contents to match with OR semantics.'
            example: 'items,shops'
        -
          in: query
          name: 'filter[min_entries]'
          description: 'Minimum combined item and shop entries.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Minimum combined item and shop entries.'
            example: 1
        -
          in: query
          name: 'filter[max_entries]'
          description: 'Maximum combined item and shop entries.'
          example: 10
          required: false
          schema:
            type: integer
            description: 'Maximum combined item and shop entries.'
            example: 10
        -
          in: query
          name: sort
          description: 'Sort column. Prefix with `-` for descending.'
          example: '-created_at'
          required: false
          schema:
            type: string
            description: 'Sort column. Prefix with `-` for descending.'
            example: '-created_at'
            enum:
              - name
              - '-name'
              - popularity
              - '-popularity'
              - created_at
              - '-created_at'
              - updated_at
              - '-updated_at'
        -
          in: query
          name: per_page
          description: 'Number of collections per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of collections per page (1-100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: ownerProfile, sharedWithProfiles, items, shops.'
          example: 'ownerProfile,sharedWithProfiles,items,shops'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: ownerProfile, sharedWithProfiles, items, shops.'
            example: 'ownerProfile,sharedWithProfiles,items,shops'
      responses:
        200:
          description: 'Paginated collection list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: collections
                      attributes:
                        name: 'Dolorem Mollitia Deleniti'
                        slug: dolorem-mollitia-deleniti
                        description: 'Odit quia officia est dignissimos neque blanditiis odio.'
                        visibility: 'Only me'
                        items_count: 0
                        shops_count: 0
                        preview_image_urls: []
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                    -
                      id: ''
                      type: collections
                      attributes:
                        name: 'Modi Rerum Ex'
                        slug: modi-rerum-ex
                        description: 'Assumenda et tenetur ab reiciendis quia.'
                        visibility: 'Only me'
                        items_count: 0
                        shops_count: 0
                        preview_image_urls: []
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: collections
                        attributes:
                          name: 'Dolorem Mollitia Deleniti'
                          slug: dolorem-mollitia-deleniti
                          description: 'Odit quia officia est dignissimos neque blanditiis odio.'
                          visibility: 'Only me'
                          items_count: 0
                          shops_count: 0
                          preview_image_urls: []
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                      -
                        id: ''
                        type: collections
                        attributes:
                          name: 'Modi Rerum Ex'
                          slug: modi-rerum-ex
                          description: 'Assumenda et tenetur ab reiciendis quia.'
                          visibility: 'Only me'
                          items_count: 0
                          shops_count: 0
                          preview_image_urls: []
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: collections
                        attributes:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'Dolorem Mollitia Deleniti'
                            slug:
                              type: string
                              example: dolorem-mollitia-deleniti
                            description:
                              type: string
                              example: 'Odit quia officia est dignissimos neque blanditiis odio.'
                            visibility:
                              type: string
                              example: 'Only me'
                            items_count:
                              type: integer
                              example: 0
                            shops_count:
                              type: integer
                              example: 0
                            preview_image_urls:
                              type: array
                              example: []
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - Collections
      security: []
    post:
      summary: 'Create Collection'
      operationId: createCollection
      description: 'Create a collection and optionally attach items and shops to it.'
      parameters: []
      responses:
        201:
          description: 'Collection created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: collections
                    attributes:
                      name: 'Et Et Modi'
                      slug: et-et-modi
                      description: 'Nostrum omnis autem et consequatur aut.'
                      visibility: 'Only me'
                      items_count: 0
                      shops_count: 0
                      preview_image_urls: []
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: collections
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Et Et Modi'
                          slug:
                            type: string
                            example: et-et-modi
                          description:
                            type: string
                            example: 'Nostrum omnis autem et consequatur aut.'
                          visibility:
                            type: string
                            example: 'Only me'
                          items_count:
                            type: integer
                            example: 0
                          shops_count:
                            type: integer
                            example: 0
                          preview_image_urls:
                            type: array
                            example: []
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Collection name.'
                  example: 'Summer Picks'
                slug:
                  type: string
                  description: 'URL slug. Generated from name when omitted.'
                  example: summer-picks
                  nullable: true
                description:
                  type: string
                  description: 'Collection description.'
                  example: 'Curated summer shops and items.'
                  nullable: true
                visibility:
                  type: string
                  description: 'Collection visibility.'
                  example: 'Only me'
                  enum:
                    - 'Only me'
                    - Friends
                    - Followers
                    - 'Friends of Friends'
                    - Public
                owner_profile_id:
                  type: string
                  description: 'Profile ULID that owns the collection.'
                  example: 01ktwg1fhzq1dpagvermfbjzad
                shared_with_profile_ids:
                  type: array
                  description: 'Profile ULIDs the collection is shared with.'
                  example:
                    - 01ktwg1fhzq1dpagvermfbjzad
                  items:
                    type: string
                item_ids:
                  type: array
                  description: 'Item ULIDs to attach to the collection.'
                  example:
                    - 01ktwg1fhzq1dpagvermfbjzad
                  items:
                    type: string
                shop_ids:
                  type: array
                  description: 'Shop ULIDs to attach to the collection.'
                  example:
                    - 01ktwg1fhzq1dpagvermfbjzad
                  items:
                    type: string
              required:
                - name
                - owner_profile_id
  '/v1/collections/{id}':
    get:
      summary: 'Show Collection'
      operationId: showCollection
      description: 'Fetch a single collection by ULID.'
      parameters:
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: ownerProfile, sharedWithProfiles, items, shops.'
          example: 'ownerProfile,items,shops'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: ownerProfile, sharedWithProfiles, items, shops.'
            example: 'ownerProfile,items,shops'
      responses:
        200:
          description: 'Collection details.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: collections
                    attributes:
                      name: 'Quos Velit Et'
                      slug: quos-velit-et
                      description: 'Sunt nihil accusantium harum mollitia.'
                      visibility: 'Only me'
                      items_count: 0
                      shops_count: 0
                      preview_image_urls: []
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: collections
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Quos Velit Et'
                          slug:
                            type: string
                            example: quos-velit-et
                          description:
                            type: string
                            example: 'Sunt nihil accusantium harum mollitia.'
                          visibility:
                            type: string
                            example: 'Only me'
                          items_count:
                            type: integer
                            example: 0
                          shops_count:
                            type: integer
                            example: 0
                          preview_image_urls:
                            type: array
                            example: []
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        404:
          description: 'Collection could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Collections
      security: []
    patch:
      summary: 'Update Collection'
      operationId: updateCollection
      description: 'Patch a collection by ULID and optionally replace its item and shop assignments.'
      parameters: []
      responses:
        200:
          description: 'Collection updated.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: collections
                    attributes:
                      name: 'Ipsum Nostrum Omnis'
                      slug: ipsum-nostrum-omnis
                      description: 'Et consequatur aut dolores enim.'
                      visibility: 'Only me'
                      items_count: 0
                      shops_count: 0
                      preview_image_urls: []
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: collections
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Ipsum Nostrum Omnis'
                          slug:
                            type: string
                            example: ipsum-nostrum-omnis
                          description:
                            type: string
                            example: 'Et consequatur aut dolores enim.'
                          visibility:
                            type: string
                            example: 'Only me'
                          items_count:
                            type: integer
                            example: 0
                          shops_count:
                            type: integer
                            example: 0
                          preview_image_urls:
                            type: array
                            example: []
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Collection could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Collections
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Collection name.'
                  example: 'Updated Summer Picks'
                slug:
                  type: string
                  description: 'New URL slug for the collection.'
                  example: updated-summer-picks
                  nullable: true
                description:
                  type: string
                  description: 'Collection description.'
                  example: 'Updated collection description.'
                  nullable: true
                visibility:
                  type: string
                  description: 'Updated collection visibility.'
                  example: Friends
                  enum:
                    - 'Only me'
                    - Friends
                    - Followers
                    - 'Friends of Friends'
                    - Public
                owner_profile_id:
                  type: string
                  description: 'Updated owner profile ULID.'
                  example: 01ktwg1fhzq1dpagvermfbjzad
                shared_with_profile_ids:
                  type: array
                  description: 'Replacement profile ULIDs the collection is shared with.'
                  example:
                    - 01ktwg1fhzq1dpagvermfbjzad
                  items:
                    type: string
                item_ids:
                  type: array
                  description: 'Replacement item ULIDs for the collection.'
                  example:
                    - 01ktwg1fhzq1dpagvermfbjzad
                  items:
                    type: string
                shop_ids:
                  type: array
                  description: 'Replacement shop ULIDs for the collection.'
                  example:
                    - 01ktwg1fhzq1dpagvermfbjzad
                  items:
                    type: string
    delete:
      summary: 'Delete Collection'
      operationId: deleteCollection
      description: 'Delete a collection by ULID.'
      parameters: []
      responses:
        204:
          description: 'Collection deleted.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Collection could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Collections
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the collection.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: collection
        description: 'The ULID of the collection.'
        example: 01ktwg1fhzq1dpagvermfbjzad
        required: true
        schema:
          type: string
  /v1/comments:
    get:
      summary: 'List Comments'
      operationId: listComments
      description: 'List comments with filtering, sorting, pagination, and optional relationship includes.'
      parameters:
        -
          in: query
          name: 'filter[search]'
          description: 'Search by comment body.'
          example: 'great update'
          required: false
          schema:
            type: string
            description: 'Search by comment body.'
            example: 'great update'
        -
          in: query
          name: 'filter[status]'
          description: 'Filter by comment status.'
          example: published
          required: false
          schema:
            type: string
            description: 'Filter by comment status.'
            example: published
            enum:
              - draft
              - published
              - archived
        -
          in: query
          name: 'filter[commentable_type]'
          description: 'Filter by commentable type alias.'
          example: post
          required: false
          schema:
            type: string
            description: 'Filter by commentable type alias.'
            example: post
            enum:
              - post
        -
          in: query
          name: 'filter[commentable_id]'
          description: 'Filter by commentable ULID.'
          example: 01jabcxyz1234567890abcdefg
          required: false
          schema:
            type: string
            description: 'Filter by commentable ULID.'
            example: 01jabcxyz1234567890abcdefg
        -
          in: query
          name: 'filter[author_id]'
          description: 'Filter by author ULID.'
          example: 01jabcxyz1234567890abcdefg
          required: false
          schema:
            type: string
            description: 'Filter by author ULID.'
            example: 01jabcxyz1234567890abcdefg
        -
          in: query
          name: 'filter[parent_comment_id]'
          description: 'Filter by parent comment ULID.'
          example: 01jabcxyz1234567890abcdefg
          required: false
          schema:
            type: string
            description: 'Filter by parent comment ULID.'
            example: 01jabcxyz1234567890abcdefg
        -
          in: query
          name: 'filter[published_from]'
          description: 'Include comments published on or after this ISO 8601 timestamp.'
          example: '2026-04-01T00:00:00Z'
          required: false
          schema:
            type: string
            description: 'Include comments published on or after this ISO 8601 timestamp.'
            example: '2026-04-01T00:00:00Z'
        -
          in: query
          name: 'filter[published_until]'
          description: 'Include comments published on or before this ISO 8601 timestamp.'
          example: '2026-04-30T23:59:59Z'
          required: false
          schema:
            type: string
            description: 'Include comments published on or before this ISO 8601 timestamp.'
            example: '2026-04-30T23:59:59Z'
        -
          in: query
          name: sort
          description: 'Sort column. Prefix with `-` for descending.'
          example: '-published_at'
          required: false
          schema:
            type: string
            description: 'Sort column. Prefix with `-` for descending.'
            example: '-published_at'
            enum:
              - created_at
              - '-created_at'
              - updated_at
              - '-updated_at'
              - published_at
              - '-published_at'
              - like_count
              - '-like_count'
              - reply_count
              - '-reply_count'
        -
          in: query
          name: per_page
          description: 'Number of comments per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of comments per page (1-100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: author, commentable, parentComment.'
          example: 'author,commentable'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: author, commentable, parentComment.'
            example: 'author,commentable'
      responses:
        200:
          description: 'Paginated comment list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: comments
                      attributes:
                        body: 'Adipisci quidem nostrum qui commodi incidunt iure.'
                        status: draft
                        like_count: 0
                        reply_count: 0
                        published_at: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                    -
                      id: ''
                      type: comments
                      attributes:
                        body: 'Id aspernatur consectetur id a consectetur assumenda.'
                        status: draft
                        like_count: 0
                        reply_count: 0
                        published_at: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: comments
                        attributes:
                          body: 'Adipisci quidem nostrum qui commodi incidunt iure.'
                          status: draft
                          like_count: 0
                          reply_count: 0
                          published_at: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                      -
                        id: ''
                        type: comments
                        attributes:
                          body: 'Id aspernatur consectetur id a consectetur assumenda.'
                          status: draft
                          like_count: 0
                          reply_count: 0
                          published_at: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: comments
                        attributes:
                          type: object
                          properties:
                            body:
                              type: string
                              example: 'Adipisci quidem nostrum qui commodi incidunt iure.'
                            status:
                              type: string
                              example: draft
                            like_count:
                              type: integer
                              example: 0
                            reply_count:
                              type: integer
                              example: 0
                            published_at:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - Comments
    post:
      summary: 'Create Comment'
      operationId: createComment
      description: 'Create a new comment for the authenticated user.'
      parameters: []
      responses:
        201:
          description: 'Comment created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: comments
                    attributes:
                      body: 'Adipisci quidem nostrum qui commodi incidunt iure.'
                      status: draft
                      like_count: 0
                      reply_count: 0
                      published_at: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: comments
                      attributes:
                        type: object
                        properties:
                          body:
                            type: string
                            example: 'Adipisci quidem nostrum qui commodi incidunt iure.'
                          status:
                            type: string
                            example: draft
                          like_count:
                            type: integer
                            example: 0
                          reply_count:
                            type: integer
                            example: 0
                          published_at:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Comments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                commentable_type:
                  type: string
                  description: 'Type alias of the model this comment belongs to.'
                  example: post
                  enum:
                    - post
                commentable_id:
                  type: string
                  description: 'ULID of the model this comment belongs to.'
                  example: 01jabcxyz1234567890abcdefg
                parent_comment_id:
                  type: string
                  description: 'Parent comment ULID for threaded replies.'
                  example: 01jabcxyz1234567890abcdefg
                  nullable: true
                body:
                  type: string
                  description: 'Comment body content.'
                  example: 'This launch looks solid.'
                  nullable: true
                status:
                  type: string
                  description: 'Comment status.'
                  example: draft
                  enum:
                    - draft
                    - published
                    - archived
                like_count:
                  type: integer
                  description: 'Initial like count.'
                  example: 0
                reply_count:
                  type: integer
                  description: 'Initial reply count.'
                  example: 0
                published_at:
                  type: string
                  description: 'Publish timestamp. Required for published comments.'
                  example: '2026-04-17T18:45:00Z'
                  nullable: true
              required:
                - commentable_type
                - commentable_id
  '/v1/comments/{id}':
    get:
      summary: 'Show Comment'
      operationId: showComment
      description: 'Fetch a single comment by ID.'
      parameters:
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: author, commentable, parentComment.'
          example: 'author,parentComment'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: author, commentable, parentComment.'
            example: 'author,parentComment'
      responses:
        200:
          description: 'Comment details.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: comments
                    attributes:
                      body: 'Adipisci quidem nostrum qui commodi incidunt iure.'
                      status: draft
                      like_count: 0
                      reply_count: 0
                      published_at: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: comments
                      attributes:
                        type: object
                        properties:
                          body:
                            type: string
                            example: 'Adipisci quidem nostrum qui commodi incidunt iure.'
                          status:
                            type: string
                            example: draft
                          like_count:
                            type: integer
                            example: 0
                          reply_count:
                            type: integer
                            example: 0
                          published_at:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Comment could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Comments
    patch:
      summary: 'Update Comment'
      operationId: updateComment
      description: 'Patch a comment by ID.'
      parameters: []
      responses:
        200:
          description: 'Comment updated.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: comments
                    attributes:
                      body: 'Adipisci quidem nostrum qui commodi incidunt iure.'
                      status: draft
                      like_count: 0
                      reply_count: 0
                      published_at: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: comments
                      attributes:
                        type: object
                        properties:
                          body:
                            type: string
                            example: 'Adipisci quidem nostrum qui commodi incidunt iure.'
                          status:
                            type: string
                            example: draft
                          like_count:
                            type: integer
                            example: 0
                          reply_count:
                            type: integer
                            example: 0
                          published_at:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Comment could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Comments
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                commentable_type:
                  type: string
                  description: 'Updated commentable type alias.'
                  example: post
                  enum:
                    - post
                commentable_id:
                  type: string
                  description: 'Updated commentable ULID.'
                  example: 01jabcxyz1234567890abcdefg
                parent_comment_id:
                  type: string
                  description: 'Updated parent comment ULID for threaded replies.'
                  example: 01jabcxyz1234567890abcdefg
                  nullable: true
                body:
                  type: string
                  description: 'Updated comment body content.'
                  example: 'Edited comment text.'
                  nullable: true
                status:
                  type: string
                  description: 'Updated comment status.'
                  example: published
                  enum:
                    - draft
                    - published
                    - archived
                like_count:
                  type: integer
                  description: 'Updated like count.'
                  example: 2
                reply_count:
                  type: integer
                  description: 'Updated reply count.'
                  example: 1
                published_at:
                  type: string
                  description: 'Publish timestamp. Required if the comment becomes published and does not already have one.'
                  example: '2026-04-17T18:45:00Z'
                  nullable: true
    delete:
      summary: 'Delete Comment'
      operationId: deleteComment
      description: 'Delete a comment by ID.'
      parameters: []
      responses:
        204:
          description: 'Comment deleted.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Comment could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Comments
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the comment.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: comment
        description: 'The ULID of the comment.'
        example: 01jabcxyz1234567890abcdefg
        required: true
        schema:
          type: string
  /v1/home-feed:
    get:
      summary: ''
      operationId: getV1HomeFeed
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/home-feed/sections/{id}':
    get:
      summary: ''
      operationId: getV1HomeFeedSectionsId
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the section.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/discover-shops:
    get:
      summary: ''
      operationId: getV1DiscoverShops
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/discover-shops/sections/{id}':
    get:
      summary: ''
      operationId: getV1DiscoverShopsSectionsId
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the section.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/discover-community-collections:
    get:
      summary: ''
      operationId: getV1DiscoverCommunityCollections
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/discover-community-collections/sections/{id}':
    get:
      summary: ''
      operationId: getV1DiscoverCommunityCollectionsSectionsId
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the section.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/categories/{category_id}/feed':
    get:
      summary: ''
      operationId: getV1CategoriesCategory_idFeed
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: category_id
        description: 'The ID of the category.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/categories/{category_id}/feed/sections/{id}':
    get:
      summary: ''
      operationId: getV1CategoriesCategory_idFeedSectionsId
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: category_id
        description: 'The ID of the category.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: id
        description: 'The ID of the section.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/admin/feed-sections:
    get:
      summary: ''
      operationId: getV1AdminFeedSections
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    post:
      summary: ''
      operationId: postV1AdminFeedSections
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/admin/feed-sections/reorder:
    post:
      summary: ''
      operationId: postV1AdminFeedSectionsReorder
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/admin/feed-sections/{section_id}':
    patch:
      summary: ''
      operationId: patchV1AdminFeedSectionsSection_id
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    delete:
      summary: ''
      operationId: deleteV1AdminFeedSectionsSection_id
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: section_id
        description: 'The ID of the section.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/admin/curated-feed-lists:
    get:
      summary: ''
      operationId: getV1AdminCuratedFeedLists
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    post:
      summary: ''
      operationId: postV1AdminCuratedFeedLists
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/admin/curated-feed-lists/{list_id}':
    patch:
      summary: ''
      operationId: patchV1AdminCuratedFeedListsList_id
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    delete:
      summary: ''
      operationId: deleteV1AdminCuratedFeedListsList_id
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: list_id
        description: 'The ID of the list.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/admin/curated-feed-lists/{list_id}/entries':
    get:
      summary: ''
      operationId: getV1AdminCuratedFeedListsList_idEntries
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    post:
      summary: ''
      operationId: postV1AdminCuratedFeedListsList_idEntries
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: list_id
        description: 'The ID of the list.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/admin/curated-feed-lists/{list_id}/entries/reorder':
    post:
      summary: ''
      operationId: postV1AdminCuratedFeedListsList_idEntriesReorder
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: list_id
        description: 'The ID of the list.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/admin/curated-feed-lists/{list_id}/entries/{entry_id}':
    delete:
      summary: ''
      operationId: deleteV1AdminCuratedFeedListsList_idEntriesEntry_id
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: list_id
        description: 'The ID of the list.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: entry_id
        description: 'The ID of the entry.'
        example: 16
        required: true
        schema:
          type: integer
  '/v1/admin/feed-curation-workspaces/{surface}':
    get:
      summary: ''
      operationId: getV1AdminFeedCurationWorkspacesSurface
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    put:
      summary: ''
      operationId: putV1AdminFeedCurationWorkspacesSurface
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: surface
        description: ''
        example: home
        required: true
        schema:
          type: string
  '/v1/admin/feed-curation-capabilities/{surface}':
    get:
      summary: ''
      operationId: getV1AdminFeedCurationCapabilitiesSurface
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: surface
        description: ''
        example: home
        required: true
        schema:
          type: string
  '/v1/admin/feed-curation-workspaces/{surface}/preview':
    post:
      summary: ''
      operationId: postV1AdminFeedCurationWorkspacesSurfacePreview
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: surface
        description: ''
        example: home
        required: true
        schema:
          type: string
  /v1/admin/section-performance:
    get:
      summary: ''
      operationId: getV1AdminSectionPerformance
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/admin/outbound-clicks:
    get:
      summary: ''
      operationId: getV1AdminOutboundClicks
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/admin/curator-token/rotate:
    post:
      summary: ''
      operationId: postV1AdminCuratorTokenRotate
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/admin/curators:
    post:
      summary: ''
      operationId: postV1AdminCurators
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/admin/curators/{curator_id}/tokens/{tokenId}':
    delete:
      summary: ''
      operationId: deleteV1AdminCuratorsCurator_idTokensTokenId
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: curator_id
        description: 'The ID of the curator.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: tokenId
        description: ''
        example: architecto
        required: true
        schema:
          type: string
  /v1/internal/analytics/entities:
    get:
      summary: ''
      operationId: getV1InternalAnalyticsEntities
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/internal/analytics/current-metrics:
    put:
      summary: ''
      operationId: putV1InternalAnalyticsCurrentMetrics
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/internal/outbound-clicks/targets/{targetType}/{targetId}':
    get:
      summary: ''
      operationId: getV1InternalOutboundClicksTargetsTargetTypeTargetId
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: targetType
        description: ''
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: targetId
        description: ''
        example: architecto
        required: true
        schema:
          type: string
  /v1/internal/recommendations/catalog:
    get:
      summary: ''
      operationId: getV1InternalRecommendationsCatalog
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/internal/ingestion/shops:onboard':
    post:
      summary: ''
      operationId: postV1InternalIngestionShopsOnboard
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/internal/authority/shops:
    get:
      summary: ''
      operationId: getV1InternalAuthorityShops
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/internal/authority/shop-catalog:
    get:
      summary: ''
      operationId: getV1InternalAuthorityShopCatalog
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/internal/authority/shop-catalog/{shop_id}':
    get:
      summary: ''
      operationId: getV1InternalAuthorityShopCatalogShop_id
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: shop_id
        description: 'The ID of the shop.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/internal/authority/publications:
    post:
      summary: ''
      operationId: postV1InternalAuthorityPublications
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/internal/authority/publications/{authorityPublication_id}/scores':
    put:
      summary: ''
      operationId: putV1InternalAuthorityPublicationsAuthorityPublication_idScores
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: authorityPublication_id
        description: 'The ID of the authorityPublication.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/internal/authority/publications/{authorityPublication_id}/activate':
    post:
      summary: ''
      operationId: postV1InternalAuthorityPublicationsAuthorityPublication_idActivate
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: authorityPublication_id
        description: 'The ID of the authorityPublication.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/internal/bot/identities/resolve:
    post:
      summary: ''
      operationId: postV1InternalBotIdentitiesResolve
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/internal/bot/link-challenges/verify:
    post:
      summary: ''
      operationId: postV1InternalBotLinkChallengesVerify
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/internal/bot/link-challenges/complete:
    post:
      summary: ''
      operationId: postV1InternalBotLinkChallengesComplete
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/internal/bot/shop-favorites:
    post:
      summary: ''
      operationId: postV1InternalBotShopFavorites
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/internal/bot/shops/{shop_id}/website-discovery-results':
    post:
      summary: ''
      operationId: postV1InternalBotShopsShop_idWebsiteDiscoveryResults
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: shop_id
        description: 'The ID of the shop.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/internal/bot/shops/{shop_id}/website-metadata-results':
    post:
      summary: ''
      operationId: postV1InternalBotShopsShop_idWebsiteMetadataResults
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: shop_id
        description: 'The ID of the shop.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/internal/bot/item-bookmarks:
    post:
      summary: ''
      operationId: postV1InternalBotItemBookmarks
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/internal/bot/resources/resolve-url:
    post:
      summary: ''
      operationId: postV1InternalBotResourcesResolveUrl
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/internal/bot/identities/{identity_id}/saved-resources':
    get:
      summary: ''
      operationId: getV1InternalBotIdentitiesIdentity_idSavedResources
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: identity_id
        description: 'The ID of the identity.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/me/channel-identities:
    get:
      summary: ''
      operationId: getV1MeChannelIdentities
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/me/channel-link-challenges:
    post:
      summary: ''
      operationId: postV1MeChannelLinkChallenges
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/me/channel-identities/{identity_id}':
    delete:
      summary: ''
      operationId: deleteV1MeChannelIdentitiesIdentity_id
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: identity_id
        description: 'The ID of the identity.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/shop-portal/auth/login:
    post:
      summary: ''
      operationId: postV1ShopPortalAuthLogin
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/shop-portal/session:
    get:
      summary: ''
      operationId: getV1ShopPortalSession
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/shop-portal/auth/logout:
    post:
      summary: ''
      operationId: postV1ShopPortalAuthLogout
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/shop-portal/sessions:
    get:
      summary: ''
      operationId: getV1ShopPortalSessions
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/shop-portal/sessions/{sessionId}':
    delete:
      summary: ''
      operationId: deleteV1ShopPortalSessionsSessionId
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: sessionId
        description: ''
        example: architecto
        required: true
        schema:
          type: string
  /v1/shop-portal/shop:
    get:
      summary: ''
      operationId: getV1ShopPortalShop
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    patch:
      summary: ''
      operationId: patchV1ShopPortalShop
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/shop-portal/items:
    get:
      summary: ''
      operationId: getV1ShopPortalItems
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/shop-portal/items/{item}':
    get:
      summary: ''
      operationId: getV1ShopPortalItemsItem
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    patch:
      summary: ''
      operationId: patchV1ShopPortalItemsItem
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: item
        description: 'The item.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/shop-portal/items/{item}/overrides/{field}/reset':
    post:
      summary: ''
      operationId: postV1ShopPortalItemsItemOverridesFieldReset
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: item
        description: 'The item.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: field
        description: ''
        example: architecto
        required: true
        schema:
          type: string
  /v1/shop-portal/reviews:
    get:
      summary: ''
      operationId: getV1ShopPortalReviews
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/shop-portal/reviews/{review}/reply':
    put:
      summary: ''
      operationId: putV1ShopPortalReviewsReviewReply
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    delete:
      summary: ''
      operationId: deleteV1ShopPortalReviewsReviewReply
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: review
        description: 'The review.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/shop-portal/team:
    get:
      summary: ''
      operationId: getV1ShopPortalTeam
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    post:
      summary: ''
      operationId: postV1ShopPortalTeam
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  '/v1/shop-portal/team/{membership}':
    delete:
      summary: ''
      operationId: deleteV1ShopPortalTeamMembership
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
    parameters:
      -
        in: path
        name: membership
        description: ''
        example: architecto
        required: true
        schema:
          type: string
  /v1/shop-portal/analytics/overview:
    get:
      summary: ''
      operationId: getV1ShopPortalAnalyticsOverview
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/shop-portal/analytics/items:
    get:
      summary: ''
      operationId: getV1ShopPortalAnalyticsItems
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/internal/analytics/metric-buckets:
    put:
      summary: ''
      operationId: putV1InternalAnalyticsMetricBuckets
      description: ''
      parameters: []
      responses: {}
      tags:
        - Endpoints
      security: []
  /v1/internal/analytics/entities/resolve:
    post:
      summary: 'Resolve analytics entities'
      operationId: resolveAnalyticsEntities
      description: 'Resolve backend entity identifiers for the analytics service.'
      parameters: []
      responses: {}
      tags:
        - 'Internal Analytics'
  /v1/internal/analytics/metric-snapshots:
    put:
      summary: 'Store analytics metric snapshots'
      operationId: storeAnalyticsMetricSnapshots
      description: 'Upsert calculated feed metric snapshots from the analytics service.'
      parameters: []
      responses: {}
      tags:
        - 'Internal Analytics'
  /v1/items:
    get:
      summary: 'List Items'
      operationId: listItems
      description: 'List items with filtering, sorting, pagination, and optional relationship includes.'
      parameters:
        -
          in: query
          name: 'filter[search]'
          description: 'Search by name, slug, description, or SKU.'
          example: sneaker
          required: false
          schema:
            type: string
            description: 'Search by name, slug, description, or SKU.'
            example: sneaker
        -
          in: query
          name: 'filter[slug]'
          description: 'Filter by exact item slug.'
          example: classic-polo-knit
          required: false
          schema:
            type: string
            description: 'Filter by exact item slug.'
            example: classic-polo-knit
        -
          in: query
          name: 'filter[is_active]'
          description: 'Filter by active status.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'Filter by active status.'
            example: true
        -
          in: query
          name: 'filter[is_available]'
          description: 'Filter by availability status.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'Filter by availability status.'
            example: true
        -
          in: query
          name: 'filter[shop_id]'
          description: 'Filter by shop ULID.'
          example: 01ktwg1fhzq1dpagvermfbjzad
          required: false
          schema:
            type: string
            description: 'Filter by shop ULID.'
            example: 01ktwg1fhzq1dpagvermfbjzad
        -
          in: query
          name: 'filter[brand_id]'
          description: 'Filter by brand ID.'
          example: null
          required: false
          schema:
            type: integer
            description: 'Filter by brand ID.'
            example: null
        -
          in: query
          name: 'filter[category_id]'
          description: 'Filter by category ULID.'
          example: 01ktwg1fhzq1dpagvermfbjzad
          required: false
          schema:
            type: string
            description: 'Filter by category ULID.'
            example: 01ktwg1fhzq1dpagvermfbjzad
        -
          in: query
          name: 'filter[condition]'
          description: 'Filter by item condition.'
          example: new
          required: false
          schema:
            type: string
            description: 'Filter by item condition.'
            example: new
            enum:
              - new
              - used
              - refurbished
              - damaged
        -
          in: query
          name: 'filter[price_min]'
          description: 'Minimum price (inclusive).'
          example: 100
          required: false
          schema:
            type: number
            description: 'Minimum price (inclusive).'
            example: 100
        -
          in: query
          name: 'filter[price_max]'
          description: 'Maximum price (inclusive).'
          example: 500
          required: false
          schema:
            type: number
            description: 'Maximum price (inclusive).'
            example: 500
        -
          in: query
          name: sort
          description: 'Sort column. Recommended sorting requires authentication and X-Profile-ID.'
          example: '-created_at'
          required: false
          schema:
            type: string
            description: 'Sort column. Recommended sorting requires authentication and X-Profile-ID.'
            example: '-created_at'
            enum:
              - recommended
              - name
              - '-name'
              - price
              - '-price'
              - popularity
              - '-popularity'
              - created_at
              - '-created_at'
              - updated_at
              - '-updated_at'
        -
          in: query
          name: per_page
          description: 'Number of items per page (1–100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of items per page (1–100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: shop, brand, categories, variants.'
          example: 'shop,brand'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: shop, brand, categories, variants.'
            example: 'shop,brand'
      responses:
        200:
          description: 'Paginated item list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: items
                      attributes:
                        name: 'Adipisci Molestias Fugit'
                        slug: adipisci-molestias-fugit
                        description: 'Distinctio eum doloremque id aut libero aliquam veniam corporis.'
                        external_url: null
                        price: 3025.43
                        original_price: null
                        currency: EGP
                        sku: NO-351-QI
                        condition: new
                        stock_level: 179
                        weight: null
                        dimensions: null
                        specifications: null
                        is_available: true
                        is_active: true
                        url: null
                        featured_image_url: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                    -
                      id: ''
                      type: items
                      attributes:
                        name: 'Officiis Corporis Nesciunt'
                        slug: officiis-corporis-nesciunt
                        description: 'Ratione iure impedit molestiae ut rem.'
                        external_url: null
                        price: 1962.84
                        original_price: null
                        currency: EGP
                        sku: RC-724-VA
                        condition: new
                        stock_level: 140
                        weight: null
                        dimensions: null
                        specifications: null
                        is_available: true
                        is_active: true
                        url: null
                        featured_image_url: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: items
                        attributes:
                          name: 'Adipisci Molestias Fugit'
                          slug: adipisci-molestias-fugit
                          description: 'Distinctio eum doloremque id aut libero aliquam veniam corporis.'
                          external_url: null
                          price: 3025.43
                          original_price: null
                          currency: EGP
                          sku: NO-351-QI
                          condition: new
                          stock_level: 179
                          weight: null
                          dimensions: null
                          specifications: null
                          is_available: true
                          is_active: true
                          url: null
                          featured_image_url: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                      -
                        id: ''
                        type: items
                        attributes:
                          name: 'Officiis Corporis Nesciunt'
                          slug: officiis-corporis-nesciunt
                          description: 'Ratione iure impedit molestiae ut rem.'
                          external_url: null
                          price: 1962.84
                          original_price: null
                          currency: EGP
                          sku: RC-724-VA
                          condition: new
                          stock_level: 140
                          weight: null
                          dimensions: null
                          specifications: null
                          is_available: true
                          is_active: true
                          url: null
                          featured_image_url: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: items
                        attributes:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'Adipisci Molestias Fugit'
                            slug:
                              type: string
                              example: adipisci-molestias-fugit
                            description:
                              type: string
                              example: 'Distinctio eum doloremque id aut libero aliquam veniam corporis.'
                            external_url:
                              type: string
                              example: null
                              nullable: true
                            price:
                              type: number
                              example: 3025.43
                            original_price:
                              type: string
                              example: null
                              nullable: true
                            currency:
                              type: string
                              example: EGP
                            sku:
                              type: string
                              example: NO-351-QI
                            condition:
                              type: string
                              example: new
                            stock_level:
                              type: integer
                              example: 179
                            weight:
                              type: string
                              example: null
                              nullable: true
                            dimensions:
                              type: string
                              example: null
                              nullable: true
                            specifications:
                              type: string
                              example: null
                              nullable: true
                            is_available:
                              type: boolean
                              example: true
                            is_active:
                              type: boolean
                              example: true
                            url:
                              type: string
                              example: null
                              nullable: true
                            featured_image_url:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - Items
      security: []
    post:
      summary: 'Create Item'
      operationId: createItem
      description: 'Create a new item record.'
      parameters: []
      responses:
        201:
          description: 'Item created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: items
                    attributes:
                      name: 'Aut Adipisci Quidem'
                      slug: aut-adipisci-quidem
                      description: 'Qui commodi incidunt iure odit.'
                      external_url: null
                      price: 568.81
                      original_price: null
                      currency: EGP
                      sku: TC-744-PS
                      condition: new
                      stock_level: 120
                      weight: null
                      dimensions: null
                      specifications: null
                      is_available: true
                      is_active: true
                      url: null
                      featured_image_url: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: items
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Aut Adipisci Quidem'
                          slug:
                            type: string
                            example: aut-adipisci-quidem
                          description:
                            type: string
                            example: 'Qui commodi incidunt iure odit.'
                          external_url:
                            type: string
                            example: null
                            nullable: true
                          price:
                            type: number
                            example: 568.81
                          original_price:
                            type: string
                            example: null
                            nullable: true
                          currency:
                            type: string
                            example: EGP
                          sku:
                            type: string
                            example: TC-744-PS
                          condition:
                            type: string
                            example: new
                          stock_level:
                            type: integer
                            example: 120
                          weight:
                            type: string
                            example: null
                            nullable: true
                          dimensions:
                            type: string
                            example: null
                            nullable: true
                          specifications:
                            type: string
                            example: null
                            nullable: true
                          is_available:
                            type: boolean
                            example: true
                          is_active:
                            type: boolean
                            example: true
                          url:
                            type: string
                            example: null
                            nullable: true
                          featured_image_url:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Items
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shop_id:
                  type: string
                  description: 'ULID of the shop this item belongs to.'
                  example: 01ktwg1fhzq1dpagvermfbjzad
                brand_id:
                  type: integer
                  description: 'ID of the brand for this item.'
                  example: 1
                  nullable: true
                name:
                  type: string
                  description: 'Item name.'
                  example: 'White Sneakers'
                slug:
                  type: string
                  description: 'URL slug. Generated from name when omitted.'
                  example: white-sneakers
                  nullable: true
                description:
                  type: string
                  description: 'Item description.'
                  example: 'Comfortable everyday sneakers.'
                  nullable: true
                price:
                  type: number
                  description: 'Selling price.'
                  example: 299.99
                  nullable: true
                original_price:
                  type: number
                  description: 'Original price before discount.'
                  example: 399.99
                  nullable: true
                currency:
                  type: string
                  description: 'ISO 4217 currency code.'
                  example: EGP
                  nullable: true
                sku:
                  type: string
                  description: 'Stock keeping unit identifier.'
                  example: SNK-WHT-42
                  nullable: true
                condition:
                  type: string
                  description: 'Item condition.'
                  example: new
                  enum:
                    - new
                    - used
                    - refurbished
                    - damaged
                  nullable: true
                stock_level:
                  type: integer
                  description: 'Current stock quantity.'
                  example: 50
                  nullable: true
                weight:
                  type: string
                  description: 'Item weight.'
                  example: 0.5kg
                  nullable: true
                dimensions:
                  type: string
                  description: 'Item dimensions.'
                  example: 30x20x10cm
                  nullable: true
                specifications:
                  type: object
                  description: 'Key-value specifications.'
                  example:
                    color: white
                    size: '42'
                  properties: {}
                  nullable: true
                is_available:
                  type: boolean
                  description: 'Whether the item is currently available.'
                  example: true
                is_active:
                  type: boolean
                  description: 'Whether the item is active.'
                  example: true
              required:
                - shop_id
                - name
  '/v1/items/{id}':
    get:
      summary: 'Show Item'
      operationId: showItem
      description: 'Fetch a single item by ULID.'
      parameters:
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: shop, brand, categories, variants.'
          example: 'shop,brand'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: shop, brand, categories, variants.'
            example: 'shop,brand'
      responses:
        200:
          description: 'Item details.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: items
                    attributes:
                      name: 'Eius Et Animi'
                      slug: eius-et-animi
                      description: 'Velit et fugiat sunt nihil accusantium.'
                      external_url: null
                      price: 1513.36
                      original_price: null
                      currency: EGP
                      sku: KH-954-WA
                      condition: new
                      stock_level: 183
                      weight: null
                      dimensions: null
                      specifications: null
                      is_available: true
                      is_active: true
                      url: null
                      featured_image_url: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: items
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Eius Et Animi'
                          slug:
                            type: string
                            example: eius-et-animi
                          description:
                            type: string
                            example: 'Velit et fugiat sunt nihil accusantium.'
                          external_url:
                            type: string
                            example: null
                            nullable: true
                          price:
                            type: number
                            example: 1513.36
                          original_price:
                            type: string
                            example: null
                            nullable: true
                          currency:
                            type: string
                            example: EGP
                          sku:
                            type: string
                            example: KH-954-WA
                          condition:
                            type: string
                            example: new
                          stock_level:
                            type: integer
                            example: 183
                          weight:
                            type: string
                            example: null
                            nullable: true
                          dimensions:
                            type: string
                            example: null
                            nullable: true
                          specifications:
                            type: string
                            example: null
                            nullable: true
                          is_available:
                            type: boolean
                            example: true
                          is_active:
                            type: boolean
                            example: true
                          url:
                            type: string
                            example: null
                            nullable: true
                          featured_image_url:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
        404:
          description: 'Item could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Items
      security: []
    patch:
      summary: 'Update Item'
      operationId: updateItem
      description: 'Patch an item by ULID.'
      parameters: []
      responses:
        200:
          description: 'Item updated.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: items
                    attributes:
                      name: 'Nostrum Qui Commodi'
                      slug: nostrum-qui-commodi
                      description: 'Iure odit et et modi ipsum nostrum omnis.'
                      external_url: null
                      price: 2911.47
                      original_price: null
                      currency: EGP
                      sku: LD-066-ZS
                      condition: new
                      stock_level: 181
                      weight: null
                      dimensions: null
                      specifications: null
                      is_available: true
                      is_active: true
                      url: null
                      featured_image_url: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: items
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Nostrum Qui Commodi'
                          slug:
                            type: string
                            example: nostrum-qui-commodi
                          description:
                            type: string
                            example: 'Iure odit et et modi ipsum nostrum omnis.'
                          external_url:
                            type: string
                            example: null
                            nullable: true
                          price:
                            type: number
                            example: 2911.47
                          original_price:
                            type: string
                            example: null
                            nullable: true
                          currency:
                            type: string
                            example: EGP
                          sku:
                            type: string
                            example: LD-066-ZS
                          condition:
                            type: string
                            example: new
                          stock_level:
                            type: integer
                            example: 181
                          weight:
                            type: string
                            example: null
                            nullable: true
                          dimensions:
                            type: string
                            example: null
                            nullable: true
                          specifications:
                            type: string
                            example: null
                            nullable: true
                          is_available:
                            type: boolean
                            example: true
                          is_active:
                            type: boolean
                            example: true
                          url:
                            type: string
                            example: null
                            nullable: true
                          featured_image_url:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Item could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Items
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Item name.'
                  example: 'White Leather Sneakers'
                slug:
                  type: string
                  description: 'New URL slug for the item.'
                  example: white-leather-sneakers
                  nullable: true
                description:
                  type: string
                  description: 'Item description.'
                  example: 'Updated description.'
                  nullable: true
                price:
                  type: number
                  description: 'Selling price.'
                  example: 249.99
                  nullable: true
                original_price:
                  type: number
                  description: 'Original price before discount.'
                  example: 399.99
                  nullable: true
                currency:
                  type: string
                  description: 'ISO 4217 currency code.'
                  example: EGP
                  nullable: true
                sku:
                  type: string
                  description: 'Stock keeping unit identifier.'
                  example: SNK-WHT-LTH-42
                  nullable: true
                condition:
                  type: string
                  description: 'Item condition.'
                  example: new
                  enum:
                    - new
                    - used
                    - refurbished
                    - damaged
                  nullable: true
                stock_level:
                  type: integer
                  description: 'Current stock quantity.'
                  example: 30
                  nullable: true
                is_available:
                  type: boolean
                  description: 'Whether the item is currently available.'
                  example: true
                is_active:
                  type: boolean
                  description: 'Whether the item is active.'
                  example: true
    delete:
      summary: 'Delete Item'
      operationId: deleteItem
      description: 'Delete an item by ULID.'
      parameters: []
      responses:
        204:
          description: 'Item deleted.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Item could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Items
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the item.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: item
        description: 'The ULID of the item.'
        example: 01ktwg1fhzq1dpagvermfbjzad
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/notifications':
    get:
      summary: 'List Notifications'
      operationId: listNotifications
      description: "List the acting profile's notifications, newest first, with cursor pagination."
      parameters:
        -
          in: query
          name: per_page
          description: 'Notifications per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Notifications per page (1-100).'
            example: 20
        -
          in: query
          name: cursor
          description: 'Cursor for the next page.'
          example: null
          required: false
          schema:
            type: string
            description: 'Cursor for the next page.'
            example: null
      responses:
        200:
          description: 'Paginated notification list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: notifications
                      attributes:
                        type: friend_request.received
                        message: 'Clara Cronin V sent you a friend request.'
                        target_url: /friends/requests
                        actor_name: 'Clara Cronin V'
                        actor_handle: wleuschke
                        actor_avatar_url: null
                        context: []
                        read_at: null
                        created_at: '2026-07-06T10:01:48+00:00'
                    -
                      id: ''
                      type: notifications
                      attributes:
                        type: friend_request.received
                        message: 'Dr. Raleigh Kreiger sent you a friend request.'
                        target_url: /friends/requests
                        actor_name: 'Dr. Raleigh Kreiger'
                        actor_handle: oklocko
                        actor_avatar_url: null
                        context: []
                        read_at: null
                        created_at: '2026-07-06T10:01:48+00:00'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: notifications
                        attributes:
                          type: friend_request.received
                          message: 'Clara Cronin V sent you a friend request.'
                          target_url: /friends/requests
                          actor_name: 'Clara Cronin V'
                          actor_handle: wleuschke
                          actor_avatar_url: null
                          context: []
                          read_at: null
                          created_at: '2026-07-06T10:01:48+00:00'
                      -
                        id: ''
                        type: notifications
                        attributes:
                          type: friend_request.received
                          message: 'Dr. Raleigh Kreiger sent you a friend request.'
                          target_url: /friends/requests
                          actor_name: 'Dr. Raleigh Kreiger'
                          actor_handle: oklocko
                          actor_avatar_url: null
                          context: []
                          read_at: null
                          created_at: '2026-07-06T10:01:48+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: notifications
                        attributes:
                          type: object
                          properties:
                            type:
                              type: string
                              example: friend_request.received
                            message:
                              type: string
                              example: 'Clara Cronin V sent you a friend request.'
                            target_url:
                              type: string
                              example: /friends/requests
                            actor_name:
                              type: string
                              example: 'Clara Cronin V'
                            actor_handle:
                              type: string
                              example: wleuschke
                            actor_avatar_url:
                              type: string
                              example: null
                              nullable: true
                            context:
                              type: array
                              example: []
                            read_at:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
      tags:
        - Notifications
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: actingProfile
        description: 'The ULID of the acting profile.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/notifications/unread-count':
    get:
      summary: 'Unread Notification Count'
      operationId: unreadNotificationCount
      description: 'Return the number of unread notifications for the acting profile.'
      parameters: []
      responses:
        200:
          description: 'Unread count.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    unread_count: 3
                properties:
                  data:
                    type: object
                    properties:
                      unread_count:
                        type: integer
                        example: 3
      tags:
        - Notifications
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: actingProfile
        description: 'The ULID of the acting profile.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/notifications/{notification_id}/read':
    patch:
      summary: 'Mark Notification Read'
      operationId: markNotificationRead
      description: 'Mark a single notification as read.'
      parameters: []
      responses:
        200:
          description: 'Notification marked read.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: notifications
                    attributes:
                      type: friend_request.received
                      message: 'Clara Cronin V sent you a friend request.'
                      target_url: /friends/requests
                      actor_name: 'Clara Cronin V'
                      actor_handle: wleuschke
                      actor_avatar_url: null
                      context: []
                      read_at: null
                      created_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: notifications
                      attributes:
                        type: object
                        properties:
                          type:
                            type: string
                            example: friend_request.received
                          message:
                            type: string
                            example: 'Clara Cronin V sent you a friend request.'
                          target_url:
                            type: string
                            example: /friends/requests
                          actor_name:
                            type: string
                            example: 'Clara Cronin V'
                          actor_handle:
                            type: string
                            example: wleuschke
                          actor_avatar_url:
                            type: string
                            example: null
                            nullable: true
                          context:
                            type: array
                            example: []
                          read_at:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        404:
          description: 'Notification does not belong to this profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Notifications
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: notification_id
        description: 'The ID of the notification.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: actingProfile
        description: 'The ULID of the acting profile.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
      -
        in: path
        name: notification
        description: 'The notification ULID.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/notifications/read-all':
    post:
      summary: 'Mark All Notifications Read'
      operationId: markAllNotificationsRead
      description: 'Mark every unread notification for the acting profile as read.'
      parameters: []
      responses:
        200:
          description: 'All notifications marked read.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    unread_count: 0
                properties:
                  data:
                    type: object
                    properties:
                      unread_count:
                        type: integer
                        example: 0
      tags:
        - Notifications
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: actingProfile
        description: 'The ULID of the acting profile.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/posts/{post_id}/like':
    post:
      summary: 'Like Post'
      operationId: likePost
      description: 'Like a post for the authenticated user.'
      parameters: []
      responses:
        200:
          description: 'Post liked.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: posts
                    attributes:
                      body: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                      status: draft
                      visibility: 'Only me'
                      repost_of_post_id: null
                      is_repost: false
                      is_quote: false
                      like_count: 0
                      reply_count: 0
                      repost_count: 0
                      liked_by_me: false
                      published_at: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: posts
                      attributes:
                        type: object
                        properties:
                          body:
                            type: string
                            example: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                          status:
                            type: string
                            example: draft
                          visibility:
                            type: string
                            example: 'Only me'
                          repost_of_post_id:
                            type: string
                            example: null
                            nullable: true
                          is_repost:
                            type: boolean
                            example: false
                          is_quote:
                            type: boolean
                            example: false
                          like_count:
                            type: integer
                            example: 0
                          reply_count:
                            type: integer
                            example: 0
                          repost_count:
                            type: integer
                            example: 0
                          liked_by_me:
                            type: boolean
                            example: false
                          published_at:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - 'Post Likes'
    delete:
      summary: 'Unlike Post'
      operationId: unlikePost
      description: 'Remove the authenticated user like from a post.'
      parameters: []
      responses:
        200:
          description: 'Post unliked.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: posts
                    attributes:
                      body: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                      status: draft
                      visibility: 'Only me'
                      repost_of_post_id: null
                      is_repost: false
                      is_quote: false
                      like_count: 0
                      reply_count: 0
                      repost_count: 0
                      liked_by_me: false
                      published_at: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: posts
                      attributes:
                        type: object
                        properties:
                          body:
                            type: string
                            example: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                          status:
                            type: string
                            example: draft
                          visibility:
                            type: string
                            example: 'Only me'
                          repost_of_post_id:
                            type: string
                            example: null
                            nullable: true
                          is_repost:
                            type: boolean
                            example: false
                          is_quote:
                            type: boolean
                            example: false
                          like_count:
                            type: integer
                            example: 0
                          reply_count:
                            type: integer
                            example: 0
                          repost_count:
                            type: integer
                            example: 0
                          liked_by_me:
                            type: boolean
                            example: false
                          published_at:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - 'Post Likes'
    parameters:
      -
        in: path
        name: post_id
        description: 'The ID of the post.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: post
        description: 'The post ULID.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  /v1/posts:
    get:
      summary: 'List Posts'
      operationId: listPosts
      description: 'List posts with filtering, sorting, pagination, and optional relationship includes.'
      parameters:
        -
          in: query
          name: 'filter[search]'
          description: 'Search by post body.'
          example: 'launch update'
          required: false
          schema:
            type: string
            description: 'Search by post body.'
            example: 'launch update'
        -
          in: query
          name: 'filter[status]'
          description: 'Filter by post status.'
          example: published
          required: false
          schema:
            type: string
            description: 'Filter by post status.'
            example: published
            enum:
              - draft
              - published
              - archived
        -
          in: query
          name: 'filter[visibility]'
          description: 'Filter by post visibility.'
          example: Public
          required: false
          schema:
            type: string
            description: 'Filter by post visibility.'
            example: Public
            enum:
              - 'Only me'
              - Friends
              - Followers
              - 'Friends of Friends'
              - Public
        -
          in: query
          name: 'filter[author_id]'
          description: 'Filter by author ULID.'
          example: 01jabcxyz1234567890abcdefg
          required: false
          schema:
            type: string
            description: 'Filter by author ULID.'
            example: 01jabcxyz1234567890abcdefg
        -
          in: query
          name: 'filter[repost_of_post_id]'
          description: 'Filter by repost source post ULID.'
          example: 01jabcxyz1234567890abcdefg
          required: false
          schema:
            type: string
            description: 'Filter by repost source post ULID.'
            example: 01jabcxyz1234567890abcdefg
        -
          in: query
          name: 'filter[published_from]'
          description: 'Include posts published on or after this ISO 8601 timestamp.'
          example: '2026-04-01T00:00:00Z'
          required: false
          schema:
            type: string
            description: 'Include posts published on or after this ISO 8601 timestamp.'
            example: '2026-04-01T00:00:00Z'
        -
          in: query
          name: 'filter[published_until]'
          description: 'Include posts published on or before this ISO 8601 timestamp.'
          example: '2026-04-30T23:59:59Z'
          required: false
          schema:
            type: string
            description: 'Include posts published on or before this ISO 8601 timestamp.'
            example: '2026-04-30T23:59:59Z'
        -
          in: query
          name: sort
          description: 'Sort column. Prefix with `-` for descending.'
          example: '-published_at'
          required: false
          schema:
            type: string
            description: 'Sort column. Prefix with `-` for descending.'
            example: '-published_at'
            enum:
              - created_at
              - '-created_at'
              - updated_at
              - '-updated_at'
              - published_at
              - '-published_at'
              - like_count
              - '-like_count'
              - reply_count
              - '-reply_count'
              - repost_count
              - '-repost_count'
        -
          in: query
          name: per_page
          description: 'Number of posts per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of posts per page (1-100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: author, repostOfPost, repostOfPost.author.'
          example: 'author,repostOfPost,repostOfPost.author'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: author, repostOfPost, repostOfPost.author.'
            example: 'author,repostOfPost,repostOfPost.author'
      responses:
        200:
          description: 'Paginated post list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: posts
                      attributes:
                        body: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                        status: draft
                        visibility: 'Only me'
                        repost_of_post_id: null
                        is_repost: false
                        is_quote: false
                        like_count: 0
                        reply_count: 0
                        repost_count: 0
                        liked_by_me: false
                        published_at: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                    -
                      id: ''
                      type: posts
                      attributes:
                        body: 'Veritatis excepturi doloribus delectus fugit. Repudiandae laboriosam est alias tenetur ratione. Voluptate accusamus ut et recusandae. Rerum ex repellendus assumenda et.'
                        status: draft
                        visibility: 'Only me'
                        repost_of_post_id: null
                        is_repost: false
                        is_quote: false
                        like_count: 0
                        reply_count: 0
                        repost_count: 0
                        liked_by_me: false
                        published_at: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: posts
                        attributes:
                          body: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                          status: draft
                          visibility: 'Only me'
                          repost_of_post_id: null
                          is_repost: false
                          is_quote: false
                          like_count: 0
                          reply_count: 0
                          repost_count: 0
                          liked_by_me: false
                          published_at: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                      -
                        id: ''
                        type: posts
                        attributes:
                          body: 'Veritatis excepturi doloribus delectus fugit. Repudiandae laboriosam est alias tenetur ratione. Voluptate accusamus ut et recusandae. Rerum ex repellendus assumenda et.'
                          status: draft
                          visibility: 'Only me'
                          repost_of_post_id: null
                          is_repost: false
                          is_quote: false
                          like_count: 0
                          reply_count: 0
                          repost_count: 0
                          liked_by_me: false
                          published_at: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: posts
                        attributes:
                          type: object
                          properties:
                            body:
                              type: string
                              example: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                            status:
                              type: string
                              example: draft
                            visibility:
                              type: string
                              example: 'Only me'
                            repost_of_post_id:
                              type: string
                              example: null
                              nullable: true
                            is_repost:
                              type: boolean
                              example: false
                            is_quote:
                              type: boolean
                              example: false
                            like_count:
                              type: integer
                              example: 0
                            reply_count:
                              type: integer
                              example: 0
                            repost_count:
                              type: integer
                              example: 0
                            liked_by_me:
                              type: boolean
                              example: false
                            published_at:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - Posts
    post:
      summary: 'Create Post'
      operationId: createPost
      description: 'Create a new post for the authenticated user.'
      parameters: []
      responses:
        201:
          description: 'Post created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: posts
                    attributes:
                      body: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                      status: draft
                      visibility: 'Only me'
                      repost_of_post_id: null
                      is_repost: false
                      is_quote: false
                      like_count: 0
                      reply_count: 0
                      repost_count: 0
                      liked_by_me: false
                      published_at: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: posts
                      attributes:
                        type: object
                        properties:
                          body:
                            type: string
                            example: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                          status:
                            type: string
                            example: draft
                          visibility:
                            type: string
                            example: 'Only me'
                          repost_of_post_id:
                            type: string
                            example: null
                            nullable: true
                          is_repost:
                            type: boolean
                            example: false
                          is_quote:
                            type: boolean
                            example: false
                          like_count:
                            type: integer
                            example: 0
                          reply_count:
                            type: integer
                            example: 0
                          repost_count:
                            type: integer
                            example: 0
                          liked_by_me:
                            type: boolean
                            example: false
                          published_at:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Posts
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                body:
                  type: string
                  description: 'Post body content.'
                  example: 'Shipping the new posts endpoint today.'
                  nullable: true
                status:
                  type: string
                  description: 'Post status.'
                  example: draft
                  enum:
                    - draft
                    - published
                    - archived
                visibility:
                  type: string
                  description: 'Post visibility.'
                  example: 'Only me'
                  enum:
                    - 'Only me'
                    - Friends
                    - Followers
                    - 'Friends of Friends'
                    - Public
                repost_of_post_id:
                  type: string
                  description: 'Source post ULID if this is a repost.'
                  example: 01jabcxyz1234567890abcdefg
                  nullable: true
                like_count:
                  type: integer
                  description: 'Initial like count.'
                  example: 0
                reply_count:
                  type: integer
                  description: 'Initial reply count.'
                  example: 0
                repost_count:
                  type: integer
                  description: 'Initial repost count.'
                  example: 0
                published_at:
                  type: string
                  description: 'Publish timestamp. Required for published posts.'
                  example: '2026-04-17T18:45:00Z'
                  nullable: true
  '/v1/posts/{id}':
    get:
      summary: 'Show Post'
      operationId: showPost
      description: 'Fetch a single post by ID.'
      parameters:
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: author, repostOfPost, repostOfPost.author.'
          example: 'author,repostOfPost,repostOfPost.author'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: author, repostOfPost, repostOfPost.author.'
            example: 'author,repostOfPost,repostOfPost.author'
      responses:
        200:
          description: 'Post details.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: posts
                    attributes:
                      body: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                      status: draft
                      visibility: 'Only me'
                      repost_of_post_id: null
                      is_repost: false
                      is_quote: false
                      like_count: 0
                      reply_count: 0
                      repost_count: 0
                      liked_by_me: false
                      published_at: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: posts
                      attributes:
                        type: object
                        properties:
                          body:
                            type: string
                            example: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                          status:
                            type: string
                            example: draft
                          visibility:
                            type: string
                            example: 'Only me'
                          repost_of_post_id:
                            type: string
                            example: null
                            nullable: true
                          is_repost:
                            type: boolean
                            example: false
                          is_quote:
                            type: boolean
                            example: false
                          like_count:
                            type: integer
                            example: 0
                          reply_count:
                            type: integer
                            example: 0
                          repost_count:
                            type: integer
                            example: 0
                          liked_by_me:
                            type: boolean
                            example: false
                          published_at:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Post could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Posts
    patch:
      summary: 'Update Post'
      operationId: updatePost
      description: 'Patch a post by ID.'
      parameters: []
      responses:
        200:
          description: 'Post updated.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: posts
                    attributes:
                      body: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                      status: draft
                      visibility: 'Only me'
                      repost_of_post_id: null
                      is_repost: false
                      is_quote: false
                      like_count: 0
                      reply_count: 0
                      repost_count: 0
                      liked_by_me: false
                      published_at: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: posts
                      attributes:
                        type: object
                        properties:
                          body:
                            type: string
                            example: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                          status:
                            type: string
                            example: draft
                          visibility:
                            type: string
                            example: 'Only me'
                          repost_of_post_id:
                            type: string
                            example: null
                            nullable: true
                          is_repost:
                            type: boolean
                            example: false
                          is_quote:
                            type: boolean
                            example: false
                          like_count:
                            type: integer
                            example: 0
                          reply_count:
                            type: integer
                            example: 0
                          repost_count:
                            type: integer
                            example: 0
                          liked_by_me:
                            type: boolean
                            example: false
                          published_at:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Post could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Posts
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                body:
                  type: string
                  description: 'Updated post body content.'
                  example: 'Edited launch message.'
                  nullable: true
                status:
                  type: string
                  description: 'Updated post status.'
                  example: published
                  enum:
                    - draft
                    - published
                    - archived
                visibility:
                  type: string
                  description: 'Updated post visibility.'
                  example: Friends
                  enum:
                    - 'Only me'
                    - Friends
                    - Followers
                    - 'Friends of Friends'
                    - Public
                repost_of_post_id:
                  type: string
                  description: 'Source post ULID if this is a repost.'
                  example: 01jabcxyz1234567890abcdefg
                  nullable: true
                like_count:
                  type: integer
                  description: 'Updated like count.'
                  example: 12
                reply_count:
                  type: integer
                  description: 'Updated reply count.'
                  example: 4
                repost_count:
                  type: integer
                  description: 'Updated repost count.'
                  example: 2
                published_at:
                  type: string
                  description: 'Publish timestamp. Required if the post becomes published and does not already have one.'
                  example: '2026-04-17T18:45:00Z'
                  nullable: true
    delete:
      summary: 'Delete Post'
      operationId: deletePost
      description: 'Delete a post by ID.'
      parameters: []
      responses:
        204:
          description: 'Post deleted.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Post could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Posts
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the post.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: post
        description: 'The ULID of the post.'
        example: 01jabcxyz1234567890abcdefg
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/blocked-profiles':
    get:
      summary: 'List Blocked Profiles'
      operationId: listBlockedProfiles
      description: 'List profiles blocked by the authenticated user profile or a target profile.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of profiles per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of profiles per page (1-100).'
            example: 20
      responses:
        200:
          description: 'Paginated blocked profile list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: daphne59
                        display_name: 'Morgan Hirthe'
                        bio: 'Libero aliquam veniam corporis dolorem mollitia deleniti.'
                        avatar_url: 'https://i.pravatar.cc/512?u=daphne59'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/daphne59'
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: modesta58
                        display_name: 'Mr. Murl Cruickshank Jr.'
                        bio: null
                        avatar_url: 'https://i.pravatar.cc/512?u=modesta58'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/modesta58'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: daphne59
                          display_name: 'Morgan Hirthe'
                          bio: 'Libero aliquam veniam corporis dolorem mollitia deleniti.'
                          avatar_url: 'https://i.pravatar.cc/512?u=daphne59'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/daphne59'
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: modesta58
                          display_name: 'Mr. Murl Cruickshank Jr.'
                          bio: null
                          avatar_url: 'https://i.pravatar.cc/512?u=modesta58'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/modesta58'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: profiles
                        attributes:
                          type: object
                          properties:
                            handle:
                              type: string
                              example: daphne59
                            display_name:
                              type: string
                              example: 'Morgan Hirthe'
                            bio:
                              type: string
                              example: 'Libero aliquam veniam corporis dolorem mollitia deleniti.'
                            avatar_url:
                              type: string
                              example: 'https://i.pravatar.cc/512?u=daphne59'
                            favorite_shops_visibility:
                              type: string
                              example: 'Only me'
                            favorite_items_visibility:
                              type: string
                              example: 'Only me'
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/profiles/daphne59'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'Profile Blocks'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'Optional parameter. The ULID of the target profile.'
        required: true
        schema:
          type: string
        examples:
          omitted:
            summary: 'When the value is omitted'
            value: ''
          present:
            summary: 'When the value is present'
            value: 01AN4Z07BY79KA1307SR9X4MV3
  '/v1/me/profiles/{actingProfile_id}/blocked-profiles/{targetProfile_id}':
    post:
      summary: 'Create Profile Block'
      operationId: createProfileBlock
      description: 'Block a profile for the authenticated user profile.'
      parameters: []
      responses:
        200:
          description: 'Profile block already exists.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile block already exists.'
                properties:
                  message:
                    type: string
                    example: 'Profile block already exists.'
        201:
          description: 'Profile block created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile block created.'
                properties:
                  message:
                    type: string
                    example: 'Profile block created.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'The target profile is the authenticated profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - 'Profile Blocks'
    delete:
      summary: 'Delete Profile Block'
      operationId: deleteProfileBlock
      description: 'Remove a profile block from the authenticated user profile.'
      parameters: []
      responses:
        200:
          description: 'Profile block deleted.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile block deleted.'
                properties:
                  message:
                    type: string
                    example: 'Profile block deleted.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'The target profile is the authenticated profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - 'Profile Blocks'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: targetProfile_id
        description: 'The ID of the targetProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'The ULID of the profile to block.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/profiles/{actingProfile_id}/blocked-profiles':
    get:
      summary: 'List Blocked Profiles'
      operationId: listBlockedProfiles
      description: 'List profiles blocked by the authenticated user profile or a target profile.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of profiles per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of profiles per page (1-100).'
            example: 20
      responses:
        200:
          description: 'Paginated blocked profile list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: cynthiafahey
                        display_name: 'Morgan Hirthe'
                        bio: 'Officia est dignissimos neque blanditiis odio veritatis excepturi.'
                        avatar_url: 'https://i.pravatar.cc/512?u=cynthiafahey'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/cynthiafahey'
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: smithroxanne
                        display_name: 'Brennon Anderson'
                        bio: null
                        avatar_url: 'https://i.pravatar.cc/512?u=smithroxanne'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/smithroxanne'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: cynthiafahey
                          display_name: 'Morgan Hirthe'
                          bio: 'Officia est dignissimos neque blanditiis odio veritatis excepturi.'
                          avatar_url: 'https://i.pravatar.cc/512?u=cynthiafahey'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/cynthiafahey'
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: smithroxanne
                          display_name: 'Brennon Anderson'
                          bio: null
                          avatar_url: 'https://i.pravatar.cc/512?u=smithroxanne'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/smithroxanne'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: profiles
                        attributes:
                          type: object
                          properties:
                            handle:
                              type: string
                              example: cynthiafahey
                            display_name:
                              type: string
                              example: 'Morgan Hirthe'
                            bio:
                              type: string
                              example: 'Officia est dignissimos neque blanditiis odio veritatis excepturi.'
                            avatar_url:
                              type: string
                              example: 'https://i.pravatar.cc/512?u=cynthiafahey'
                            favorite_shops_visibility:
                              type: string
                              example: 'Only me'
                            favorite_items_visibility:
                              type: string
                              example: 'Only me'
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/profiles/cynthiafahey'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'Profile Blocks'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'Optional parameter. The ULID of the target profile.'
        required: true
        schema:
          type: string
        examples:
          omitted:
            summary: 'When the value is omitted'
            value: ''
          present:
            summary: 'When the value is present'
            value: 01AN4Z07BY79KA1307SR9X4MV3
  '/v1/me/profiles/{actingProfile_id}/friend-requests/incoming':
    get:
      summary: 'List Incoming Profile Friend Requests'
      operationId: listIncomingProfileFriendRequests
      description: 'List pending friend requests received by the authenticated user profile.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of requests per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of requests per page (1-100).'
            example: 20
      responses:
        200:
          description: 'Paginated incoming friend request list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: profile-friend-requests
                      attributes:
                        requester_profile_id: 01kwve0y0dq6tzdc18cxxypme7
                        recipient_profile_id: 01kwve0y0hdxnbys5jzdyrqh42
                        created_at: null
                        updated_at: null
                    -
                      id: ''
                      type: profile-friend-requests
                      attributes:
                        requester_profile_id: 01kwve0y0ndxrm4ggtm6f61svp
                        recipient_profile_id: 01kwve0y0s2vz1gc4r09ythx6p
                        created_at: null
                        updated_at: null
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: profile-friend-requests
                        attributes:
                          requester_profile_id: 01kwve0y0dq6tzdc18cxxypme7
                          recipient_profile_id: 01kwve0y0hdxnbys5jzdyrqh42
                          created_at: null
                          updated_at: null
                      -
                        id: ''
                        type: profile-friend-requests
                        attributes:
                          requester_profile_id: 01kwve0y0ndxrm4ggtm6f61svp
                          recipient_profile_id: 01kwve0y0s2vz1gc4r09ythx6p
                          created_at: null
                          updated_at: null
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: profile-friend-requests
                        attributes:
                          type: object
                          properties:
                            requester_profile_id:
                              type: string
                              example: 01kwve0y0dq6tzdc18cxxypme7
                            recipient_profile_id:
                              type: string
                              example: 01kwve0y0hdxnbys5jzdyrqh42
                            created_at:
                              type: string
                              example: null
                              nullable: true
                            updated_at:
                              type: string
                              example: null
                              nullable: true
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Authenticated user profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'Profile Friend Requests'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/friend-requests/outgoing':
    get:
      summary: 'List Outgoing Profile Friend Requests'
      operationId: listOutgoingProfileFriendRequests
      description: 'List pending friend requests sent by the authenticated user profile.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of requests per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of requests per page (1-100).'
            example: 20
      responses:
        200:
          description: 'Paginated outgoing friend request list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: profile-friend-requests
                      attributes:
                        requester_profile_id: 01kwve0y0y57x02dbffmf895x3
                        recipient_profile_id: 01kwve0y12qhz36bzkbh0637bp
                        created_at: null
                        updated_at: null
                    -
                      id: ''
                      type: profile-friend-requests
                      attributes:
                        requester_profile_id: 01kwve0y16m6m88jhgjexag9as
                        recipient_profile_id: 01kwve0y19w2se3se86r17caxy
                        created_at: null
                        updated_at: null
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: profile-friend-requests
                        attributes:
                          requester_profile_id: 01kwve0y0y57x02dbffmf895x3
                          recipient_profile_id: 01kwve0y12qhz36bzkbh0637bp
                          created_at: null
                          updated_at: null
                      -
                        id: ''
                        type: profile-friend-requests
                        attributes:
                          requester_profile_id: 01kwve0y16m6m88jhgjexag9as
                          recipient_profile_id: 01kwve0y19w2se3se86r17caxy
                          created_at: null
                          updated_at: null
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: profile-friend-requests
                        attributes:
                          type: object
                          properties:
                            requester_profile_id:
                              type: string
                              example: 01kwve0y0y57x02dbffmf895x3
                            recipient_profile_id:
                              type: string
                              example: 01kwve0y12qhz36bzkbh0637bp
                            created_at:
                              type: string
                              example: null
                              nullable: true
                            updated_at:
                              type: string
                              example: null
                              nullable: true
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Authenticated user profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'Profile Friend Requests'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/friend-requests/{targetProfile_id}':
    post:
      summary: 'Create Profile Friend Request'
      operationId: createProfileFriendRequest
      description: 'Send a pending friend request to another profile. A reciprocal pending request is accepted automatically.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Friend request already exists.'
                    type: object
                    example:
                      message: 'Profile friend request already exists.'
                    properties:
                      message:
                        type: string
                        example: 'Profile friend request already exists.'
                  -
                    description: 'Reciprocal request accepted automatically.'
                    type: object
                    example:
                      message: 'Profile friend request accepted.'
                    properties:
                      message:
                        type: string
                        example: 'Profile friend request accepted.'
        201:
          description: 'Friend request created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile friend request created.'
                properties:
                  message:
                    type: string
                    example: 'Profile friend request created.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        409:
          description: 'Either profile has blocked the other.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Blocked profiles cannot become friends.'
                properties:
                  message:
                    type: string
                    example: 'Blocked profiles cannot become friends.'
        422:
          description: 'The target profile is the authenticated profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - 'Profile Friend Requests'
    delete:
      summary: 'Cancel Profile Friend Request'
      operationId: cancelProfileFriendRequest
      description: 'Cancel an outgoing pending friend request to another profile.'
      parameters: []
      responses:
        200:
          description: 'Friend request canceled.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile friend request canceled.'
                properties:
                  message:
                    type: string
                    example: 'Profile friend request canceled.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'The target profile is the authenticated profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - 'Profile Friend Requests'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: targetProfile_id
        description: 'The ID of the targetProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'The ULID of the profile to request.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/friend-requests/{targetProfile_id}/accept':
    post:
      summary: 'Accept Profile Friend Request'
      operationId: acceptProfileFriendRequest
      description: 'Accept an incoming pending friend request from another profile.'
      parameters: []
      responses:
        200:
          description: 'Friend request accepted.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile friend request accepted.'
                properties:
                  message:
                    type: string
                    example: 'Profile friend request accepted.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Incoming request could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile friend request not found.'
                properties:
                  message:
                    type: string
                    example: 'Profile friend request not found.'
        422:
          description: 'The target profile is the authenticated profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - 'Profile Friend Requests'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: targetProfile_id
        description: 'The ID of the targetProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'The ULID of the requester profile.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/friend-requests/{targetProfile_id}/decline':
    post:
      summary: 'Decline Profile Friend Request'
      operationId: declineProfileFriendRequest
      description: 'Decline an incoming pending friend request from another profile.'
      parameters: []
      responses:
        200:
          description: 'Friend request declined.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile friend request declined.'
                properties:
                  message:
                    type: string
                    example: 'Profile friend request declined.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'The target profile is the authenticated profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - 'Profile Friend Requests'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: targetProfile_id
        description: 'The ID of the targetProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'The ULID of the requester profile.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/friends':
    get:
      summary: 'List Profile Friends'
      operationId: listProfileFriends
      description: 'List friends for the authenticated user profile or a target profile.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of profiles per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of profiles per page (1-100).'
            example: 20
      responses:
        200:
          description: 'Paginated profile friend list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: sleffler
                        display_name: 'Morgan Hirthe'
                        bio: null
                        avatar_url: 'https://i.pravatar.cc/512?u=sleffler'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/sleffler'
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: micaela88
                        display_name: 'Prof. Annabelle Kshlerin'
                        bio: 'Veniam corporis dolorem mollitia.'
                        avatar_url: 'https://i.pravatar.cc/512?u=micaela88'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/micaela88'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: sleffler
                          display_name: 'Morgan Hirthe'
                          bio: null
                          avatar_url: 'https://i.pravatar.cc/512?u=sleffler'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/sleffler'
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: micaela88
                          display_name: 'Prof. Annabelle Kshlerin'
                          bio: 'Veniam corporis dolorem mollitia.'
                          avatar_url: 'https://i.pravatar.cc/512?u=micaela88'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/micaela88'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: profiles
                        attributes:
                          type: object
                          properties:
                            handle:
                              type: string
                              example: sleffler
                            display_name:
                              type: string
                              example: 'Morgan Hirthe'
                            bio:
                              type: string
                              example: null
                              nullable: true
                            avatar_url:
                              type: string
                              example: 'https://i.pravatar.cc/512?u=sleffler'
                            favorite_shops_visibility:
                              type: string
                              example: 'Only me'
                            favorite_items_visibility:
                              type: string
                              example: 'Only me'
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/profiles/sleffler'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'Profile Friends'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'Optional parameter. The ULID of the target profile.'
        required: true
        schema:
          type: string
        examples:
          omitted:
            summary: 'When the value is omitted'
            value: ''
          present:
            summary: 'When the value is present'
            value: 01AN4Z07BY79KA1307SR9X4MV3
  '/v1/me/profiles/{actingProfile_id}/friends-of-friends':
    get:
      summary: 'List Profile Friends Of Friends'
      operationId: listProfileFriendsOfFriends
      description: 'List second-degree friends for the authenticated user profile or a target profile.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of profiles per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of profiles per page (1-100).'
            example: 20
      responses:
        200:
          description: 'Paginated friends-of-friends list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: matildafeeney
                        display_name: 'Morgan Hirthe'
                        bio: null
                        avatar_url: 'https://i.pravatar.cc/512?u=matildafeeney'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/matildafeeney'
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: verlie08
                        display_name: 'Kirstin Nitzsche V'
                        bio: 'Deleniti nemo odit quia officia.'
                        avatar_url: 'https://i.pravatar.cc/512?u=verlie08'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/verlie08'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: matildafeeney
                          display_name: 'Morgan Hirthe'
                          bio: null
                          avatar_url: 'https://i.pravatar.cc/512?u=matildafeeney'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/matildafeeney'
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: verlie08
                          display_name: 'Kirstin Nitzsche V'
                          bio: 'Deleniti nemo odit quia officia.'
                          avatar_url: 'https://i.pravatar.cc/512?u=verlie08'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/verlie08'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: profiles
                        attributes:
                          type: object
                          properties:
                            handle:
                              type: string
                              example: matildafeeney
                            display_name:
                              type: string
                              example: 'Morgan Hirthe'
                            bio:
                              type: string
                              example: null
                              nullable: true
                            avatar_url:
                              type: string
                              example: 'https://i.pravatar.cc/512?u=matildafeeney'
                            favorite_shops_visibility:
                              type: string
                              example: 'Only me'
                            favorite_items_visibility:
                              type: string
                              example: 'Only me'
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/profiles/matildafeeney'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'Profile Friends'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'Optional parameter. The ULID of the target profile.'
        required: true
        schema:
          type: string
        examples:
          omitted:
            summary: 'When the value is omitted'
            value: ''
          present:
            summary: 'When the value is present'
            value: 01AN4Z07BY79KA1307SR9X4MV3
  '/v1/me/profiles/{actingProfile_id}/friends/{targetProfile_id}':
    delete:
      summary: 'Delete Profile Friend'
      operationId: deleteProfileFriend
      description: 'Remove a friendship from the authenticated user profile.'
      parameters: []
      responses:
        200:
          description: 'Profile friendship deleted.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile friend deleted.'
                properties:
                  message:
                    type: string
                    example: 'Profile friend deleted.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'The target profile is the authenticated profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - 'Profile Friends'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: targetProfile_id
        description: 'The ID of the targetProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'The ULID of the profile to unfriend.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/profiles/{actingProfile_id}/friends':
    get:
      summary: 'List Profile Friends'
      operationId: listProfileFriends
      description: 'List friends for the authenticated user profile or a target profile.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of profiles per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of profiles per page (1-100).'
            example: 20
      responses:
        200:
          description: 'Paginated profile friend list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: qankunding
                        display_name: 'Morgan Hirthe'
                        bio: 'Corporis dolorem mollitia deleniti nemo odit quia officia.'
                        avatar_url: 'https://i.pravatar.cc/512?u=qankunding'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/qankunding'
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: gthiel
                        display_name: 'Mona Lemke'
                        bio: null
                        avatar_url: 'https://i.pravatar.cc/512?u=gthiel'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/gthiel'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: qankunding
                          display_name: 'Morgan Hirthe'
                          bio: 'Corporis dolorem mollitia deleniti nemo odit quia officia.'
                          avatar_url: 'https://i.pravatar.cc/512?u=qankunding'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/qankunding'
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: gthiel
                          display_name: 'Mona Lemke'
                          bio: null
                          avatar_url: 'https://i.pravatar.cc/512?u=gthiel'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/gthiel'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: profiles
                        attributes:
                          type: object
                          properties:
                            handle:
                              type: string
                              example: qankunding
                            display_name:
                              type: string
                              example: 'Morgan Hirthe'
                            bio:
                              type: string
                              example: 'Corporis dolorem mollitia deleniti nemo odit quia officia.'
                            avatar_url:
                              type: string
                              example: 'https://i.pravatar.cc/512?u=qankunding'
                            favorite_shops_visibility:
                              type: string
                              example: 'Only me'
                            favorite_items_visibility:
                              type: string
                              example: 'Only me'
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/profiles/qankunding'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'Profile Friends'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'Optional parameter. The ULID of the target profile.'
        required: true
        schema:
          type: string
        examples:
          omitted:
            summary: 'When the value is omitted'
            value: ''
          present:
            summary: 'When the value is present'
            value: 01AN4Z07BY79KA1307SR9X4MV3
  '/v1/profiles/{actingProfile_id}/friends-of-friends':
    get:
      summary: 'List Profile Friends Of Friends'
      operationId: listProfileFriendsOfFriends
      description: 'List second-degree friends for the authenticated user profile or a target profile.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of profiles per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of profiles per page (1-100).'
            example: 20
      responses:
        200:
          description: 'Paginated friends-of-friends list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: wbatz
                        display_name: 'Morgan Hirthe'
                        bio: 'Deleniti nemo odit quia officia.'
                        avatar_url: 'https://i.pravatar.cc/512?u=wbatz'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/wbatz'
                    -
                      id: ''
                      type: profiles
                      attributes:
                        handle: walker26
                        display_name: 'Alexa Hamill DDS'
                        bio: null
                        avatar_url: 'https://i.pravatar.cc/512?u=walker26'
                        favorite_shops_visibility: 'Only me'
                        favorite_items_visibility: 'Only me'
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/profiles/walker26'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: wbatz
                          display_name: 'Morgan Hirthe'
                          bio: 'Deleniti nemo odit quia officia.'
                          avatar_url: 'https://i.pravatar.cc/512?u=wbatz'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/wbatz'
                      -
                        id: ''
                        type: profiles
                        attributes:
                          handle: walker26
                          display_name: 'Alexa Hamill DDS'
                          bio: null
                          avatar_url: 'https://i.pravatar.cc/512?u=walker26'
                          favorite_shops_visibility: 'Only me'
                          favorite_items_visibility: 'Only me'
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/profiles/walker26'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: profiles
                        attributes:
                          type: object
                          properties:
                            handle:
                              type: string
                              example: wbatz
                            display_name:
                              type: string
                              example: 'Morgan Hirthe'
                            bio:
                              type: string
                              example: 'Deleniti nemo odit quia officia.'
                            avatar_url:
                              type: string
                              example: 'https://i.pravatar.cc/512?u=wbatz'
                            favorite_shops_visibility:
                              type: string
                              example: 'Only me'
                            favorite_items_visibility:
                              type: string
                              example: 'Only me'
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/profiles/wbatz'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'Profile Friends'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: profile
        description: 'Optional parameter. The ULID of the target profile.'
        required: true
        schema:
          type: string
        examples:
          omitted:
            summary: 'When the value is omitted'
            value: ''
          present:
            summary: 'When the value is present'
            value: 01AN4Z07BY79KA1307SR9X4MV3
  '/v1/profiles/{handle}':
    get:
      summary: 'Show Profile'
      operationId: showProfile
      description: 'Fetch a profile by handle.'
      parameters: []
      responses:
        200:
          description: 'Profile found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: profiles
                    attributes:
                      handle: dareemelie
                      display_name: 'Morgan Hirthe'
                      bio: null
                      avatar_url: 'https://i.pravatar.cc/512?u=dareemelie'
                      favorite_shops_visibility: 'Only me'
                      favorite_items_visibility: 'Only me'
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/profiles/dareemelie'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: profiles
                      attributes:
                        type: object
                        properties:
                          handle:
                            type: string
                            example: dareemelie
                          display_name:
                            type: string
                            example: 'Morgan Hirthe'
                          bio:
                            type: string
                            example: null
                            nullable: true
                          avatar_url:
                            type: string
                            example: 'https://i.pravatar.cc/512?u=dareemelie'
                          favorite_shops_visibility:
                            type: string
                            example: 'Only me'
                          favorite_items_visibility:
                            type: string
                            example: 'Only me'
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/profiles/dareemelie'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Profiles
    parameters:
      -
        in: path
        name: handle
        description: 'The profile handle.'
        example: jane_doe
        required: true
        schema:
          type: string
  /v1/me/profiles:
    get:
      summary: 'List Current User Profiles'
      operationId: listCurrentUserProfiles
      description: 'List profiles owned by the authenticated user.'
      parameters: []
      responses: {}
      tags:
        - Profiles
    post:
      summary: 'Create Current User Profile'
      operationId: createCurrentUserProfile
      description: 'Create the authenticated user profile.'
      parameters: []
      responses:
        201:
          description: 'Profile created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: profiles
                    attributes:
                      handle: alayna44
                      display_name: 'Morgan Hirthe'
                      bio: 'Nostrum omnis autem et consequatur aut.'
                      avatar_url: 'https://i.pravatar.cc/512?u=alayna44'
                      favorite_shops_visibility: 'Only me'
                      favorite_items_visibility: 'Only me'
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/profiles/alayna44'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: profiles
                      attributes:
                        type: object
                        properties:
                          handle:
                            type: string
                            example: alayna44
                          display_name:
                            type: string
                            example: 'Morgan Hirthe'
                          bio:
                            type: string
                            example: 'Nostrum omnis autem et consequatur aut.'
                          avatar_url:
                            type: string
                            example: 'https://i.pravatar.cc/512?u=alayna44'
                          favorite_shops_visibility:
                            type: string
                            example: 'Only me'
                          favorite_items_visibility:
                            type: string
                            example: 'Only me'
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/profiles/alayna44'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        409:
          description: 'Current user already has a profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Profile already exists.'
                properties:
                  message:
                    type: string
                    example: 'Profile already exists.'
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Profiles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                handle:
                  type: string
                  description: 'Unique profile handle.'
                  example: jane_doe
                display_name:
                  type: string
                  description: 'Public display name.'
                  example: 'Jane Doe'
                  nullable: true
                bio:
                  type: string
                  description: 'Public profile biography.'
                  example: 'Curating local shops and finds.'
                  nullable: true
                avatar_url:
                  type: string
                  description: 'Public avatar URL.'
                  example: 'https://i.pravatar.cc/512?u=jane_doe'
                  nullable: true
                favorite_shops_visibility:
                  type: string
                  description: 'Favorite shops visibility.'
                  example: Public
                  enum:
                    - 'Only me'
                    - Friends
                    - Followers
                    - 'Friends of Friends'
                    - Public
                favorite_items_visibility:
                  type: string
                  description: 'Favorite items visibility.'
                  example: 'Only me'
                  enum:
                    - 'Only me'
                    - Friends
                    - Followers
                    - 'Friends of Friends'
                    - Public
              required:
                - handle
  '/v1/me/profiles/{actingProfile_id}':
    get:
      summary: 'Show Current User Profile'
      operationId: showCurrentUserProfile
      description: 'Fetch the authenticated user profile.'
      parameters: []
      responses:
        200:
          description: 'Current user profile.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: profiles
                    attributes:
                      handle: pfritsch
                      display_name: 'Morgan Hirthe'
                      bio: null
                      avatar_url: 'https://i.pravatar.cc/512?u=pfritsch'
                      favorite_shops_visibility: 'Only me'
                      favorite_items_visibility: 'Only me'
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/profiles/pfritsch'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: profiles
                      attributes:
                        type: object
                        properties:
                          handle:
                            type: string
                            example: pfritsch
                          display_name:
                            type: string
                            example: 'Morgan Hirthe'
                          bio:
                            type: string
                            example: null
                            nullable: true
                          avatar_url:
                            type: string
                            example: 'https://i.pravatar.cc/512?u=pfritsch'
                          favorite_shops_visibility:
                            type: string
                            example: 'Only me'
                          favorite_items_visibility:
                            type: string
                            example: 'Only me'
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/profiles/pfritsch'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Profiles
    patch:
      summary: 'Update Current User Profile'
      operationId: updateCurrentUserProfile
      description: 'Patch the authenticated user profile.'
      parameters: []
      responses:
        200:
          description: 'Profile updated.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: profiles
                    attributes:
                      handle: carey67
                      display_name: 'Morgan Hirthe'
                      bio: null
                      avatar_url: 'https://i.pravatar.cc/512?u=carey67'
                      favorite_shops_visibility: 'Only me'
                      favorite_items_visibility: 'Only me'
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/profiles/carey67'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: profiles
                      attributes:
                        type: object
                        properties:
                          handle:
                            type: string
                            example: carey67
                          display_name:
                            type: string
                            example: 'Morgan Hirthe'
                          bio:
                            type: string
                            example: null
                            nullable: true
                          avatar_url:
                            type: string
                            example: 'https://i.pravatar.cc/512?u=carey67'
                          favorite_shops_visibility:
                            type: string
                            example: 'Only me'
                          favorite_items_visibility:
                            type: string
                            example: 'Only me'
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/profiles/carey67'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Profiles
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                handle:
                  type: string
                  description: 'Unique profile handle.'
                  example: jane_doe_updated
                display_name:
                  type: string
                  description: 'Public display name.'
                  example: 'Jane Doe'
                  nullable: true
                bio:
                  type: string
                  description: 'Public profile biography.'
                  example: 'Updated profile biography.'
                  nullable: true
                avatar_url:
                  type: string
                  description: 'Public avatar URL.'
                  example: 'https://i.pravatar.cc/512?u=jane_doe_updated'
                  nullable: true
                favorite_shops_visibility:
                  type: string
                  description: 'Favorite shops visibility.'
                  example: Followers
                  enum:
                    - 'Only me'
                    - Friends
                    - Followers
                    - 'Friends of Friends'
                    - Public
                favorite_items_visibility:
                  type: string
                  description: 'Favorite items visibility.'
                  example: Friends
                  enum:
                    - 'Only me'
                    - Friends
                    - Followers
                    - 'Friends of Friends'
                    - Public
    delete:
      summary: 'Delete Current User Profile'
      operationId: deleteCurrentUserProfile
      description: 'Delete the authenticated user profile.'
      parameters: []
      responses:
        204:
          description: 'Profile deleted.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Profiles
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/search':
    get:
      summary: 'Search Profiles'
      operationId: searchProfiles
      description: 'Search profiles by display name or handle for the acting profile.'
      parameters:
        -
          in: query
          name: search
          description: 'Display name or handle search term.'
          example: jane
          required: true
          schema:
            type: string
            description: 'Display name or handle search term.'
            example: jane
      responses: {}
      tags:
        - Profiles
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/posts':
    get:
      summary: 'List My Profile Posts'
      operationId: listMyProfilePosts
      description: 'List published timeline posts for the authenticated user profile, including repost rows.'
      parameters:
        -
          in: query
          name: sort
          description: 'Sort column. Prefix with `-` for descending.'
          example: '-published_at'
          required: false
          schema:
            type: string
            description: 'Sort column. Prefix with `-` for descending.'
            example: '-published_at'
            enum:
              - created_at
              - '-created_at'
              - published_at
              - '-published_at'
        -
          in: query
          name: per_page
          description: 'Number of posts per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of posts per page (1-100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: author, repostOfPost, repostOfPost.author.'
          example: 'author,repostOfPost,repostOfPost.author'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: author, repostOfPost, repostOfPost.author.'
            example: 'author,repostOfPost,repostOfPost.author'
      responses:
        200:
          description: 'Paginated current profile post list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: posts
                      attributes:
                        body: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                        status: draft
                        visibility: 'Only me'
                        repost_of_post_id: null
                        is_repost: false
                        is_quote: false
                        like_count: 0
                        reply_count: 0
                        repost_count: 0
                        liked_by_me: false
                        published_at: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                    -
                      id: ''
                      type: posts
                      attributes:
                        body: 'Sit doloremque aut omnis quo sit. Mollitia aut rerum ipsa dolorem alias sapiente omnis harum. Itaque voluptas iste esse nesciunt optio.'
                        status: draft
                        visibility: 'Only me'
                        repost_of_post_id: null
                        is_repost: false
                        is_quote: false
                        like_count: 0
                        reply_count: 0
                        repost_count: 0
                        liked_by_me: false
                        published_at: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: posts
                        attributes:
                          body: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                          status: draft
                          visibility: 'Only me'
                          repost_of_post_id: null
                          is_repost: false
                          is_quote: false
                          like_count: 0
                          reply_count: 0
                          repost_count: 0
                          liked_by_me: false
                          published_at: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                      -
                        id: ''
                        type: posts
                        attributes:
                          body: 'Sit doloremque aut omnis quo sit. Mollitia aut rerum ipsa dolorem alias sapiente omnis harum. Itaque voluptas iste esse nesciunt optio.'
                          status: draft
                          visibility: 'Only me'
                          repost_of_post_id: null
                          is_repost: false
                          is_quote: false
                          like_count: 0
                          reply_count: 0
                          repost_count: 0
                          liked_by_me: false
                          published_at: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: posts
                        attributes:
                          type: object
                          properties:
                            body:
                              type: string
                              example: 'Quidem nostrum qui commodi incidunt iure odit. Et modi ipsum nostrum omnis autem et consequatur. Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci.'
                            status:
                              type: string
                              example: draft
                            visibility:
                              type: string
                              example: 'Only me'
                            repost_of_post_id:
                              type: string
                              example: null
                              nullable: true
                            is_repost:
                              type: boolean
                              example: false
                            is_quote:
                              type: boolean
                              example: false
                            like_count:
                              type: integer
                              example: 0
                            reply_count:
                              type: integer
                              example: 0
                            repost_count:
                              type: integer
                              example: 0
                            liked_by_me:
                              type: boolean
                              example: false
                            published_at:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Current user profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Profiles
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/referrals/validate:
    post:
      summary: 'Validate Referral Code'
      operationId: validateReferralCode
      description: 'Check whether a referral code can be used during registration.'
      parameters: []
      responses:
        200:
          description: 'Validation result.'
          content:
            application/json:
              schema:
                type: object
                example:
                  valid: true
                properties:
                  valid:
                    type: boolean
                    example: true
      tags:
        - Referrals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                referral_code:
                  type: string
                  description: 'Referral code to validate.'
                  example: AbCdEfGhIjKlMnOpQrStUv
              required:
                - referral_code
      security: []
  '/v1/me/profiles/{actingProfile_id}/referral':
    get:
      summary: 'Show Profile Referral'
      operationId: showProfileReferral
      description: 'Return the stable referral code and registration URL for an owned profile.'
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  code: AbCdEfGhIjKlMnOpQrStUv
                  url: 'https://frontend.bazaarspot-api.test/register?referral_code=AbCdEfGhIjKlMnOpQrStUv'
                properties:
                  code:
                    type: string
                    example: AbCdEfGhIjKlMnOpQrStUv
                  url:
                    type: string
                    example: 'https://frontend.bazaarspot-api.test/register?referral_code=AbCdEfGhIjKlMnOpQrStUv'
      tags:
        - Referrals
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: actingProfile
        description: 'Owned profile ULID.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/reviews:
    get:
      summary: 'List Reviews'
      operationId: listReviews
      description: 'List shop and item reviews with filtering, sorting, pagination, and optional relationship includes.'
      parameters:
        -
          in: query
          name: 'filter[search]'
          description: 'Search by review title or body.'
          example: 'fast shipping'
          required: false
          schema:
            type: string
            description: 'Search by review title or body.'
            example: 'fast shipping'
        -
          in: query
          name: 'filter[shop_id]'
          description: 'Filter by shop ULID.'
          example: 01jabcxyz1234567890abcdefg
          required: false
          schema:
            type: string
            description: 'Filter by shop ULID.'
            example: 01jabcxyz1234567890abcdefg
        -
          in: query
          name: 'filter[item_id]'
          description: 'Filter by item ULID.'
          example: 01jabcxyz1234567890abcdefg
          required: false
          schema:
            type: string
            description: 'Filter by item ULID.'
            example: 01jabcxyz1234567890abcdefg
        -
          in: query
          name: 'filter[user_id]'
          description: 'Filter by reviewer user ULID.'
          example: 01jabcxyz1234567890abcdefg
          required: false
          schema:
            type: string
            description: 'Filter by reviewer user ULID.'
            example: 01jabcxyz1234567890abcdefg
        -
          in: query
          name: 'filter[rating]'
          description: 'Filter by exact rating from 1 to 5.'
          example: 5
          required: false
          schema:
            type: integer
            description: 'Filter by exact rating from 1 to 5.'
            example: 5
        -
          in: query
          name: sort
          description: 'Sort column. Prefix with `-` for descending.'
          example: '-created_at'
          required: false
          schema:
            type: string
            description: 'Sort column. Prefix with `-` for descending.'
            example: '-created_at'
            enum:
              - created_at
              - '-created_at'
              - updated_at
              - '-updated_at'
              - rating
              - '-rating'
        -
          in: query
          name: per_page
          description: 'Number of reviews per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of reviews per page (1-100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: item, shop, user, reply.'
          example: 'item,shop,user,reply'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: item, shop, user, reply.'
            example: 'item,shop,user,reply'
      responses:
        200:
          description: 'Paginated review list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: reviews
                      attributes:
                        title: null
                        body: 'Nostrum qui commodi incidunt iure.'
                        rating: 5
                        target_type: shop
                        target_id: 01kwve0y54ek2kerfcyzmqqsd0
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
                    -
                      id: ''
                      type: reviews
                      attributes:
                        title: 'Et recusandae modi rerum ex.'
                        body: null
                        rating: 1
                        target_type: shop
                        target_id: 01kwve0y58665m2f9ztdsvbk26
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: reviews
                        attributes:
                          title: null
                          body: 'Nostrum qui commodi incidunt iure.'
                          rating: 5
                          target_type: shop
                          target_id: 01kwve0y54ek2kerfcyzmqqsd0
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
                      -
                        id: ''
                        type: reviews
                        attributes:
                          title: 'Et recusandae modi rerum ex.'
                          body: null
                          rating: 1
                          target_type: shop
                          target_id: 01kwve0y58665m2f9ztdsvbk26
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: reviews
                        attributes:
                          type: object
                          properties:
                            title:
                              type: string
                              example: null
                              nullable: true
                            body:
                              type: string
                              example: 'Nostrum qui commodi incidunt iure.'
                            rating:
                              type: integer
                              example: 5
                            target_type:
                              type: string
                              example: shop
                            target_id:
                              type: string
                              example: 01kwve0y54ek2kerfcyzmqqsd0
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - Reviews
    post:
      summary: 'Create Review'
      operationId: createReview
      description: 'Create a new review for a shop or item.'
      parameters: []
      responses:
        201:
          description: 'Review created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: reviews
                    attributes:
                      title: null
                      body: 'Nostrum qui commodi incidunt iure.'
                      rating: 5
                      target_type: shop
                      target_id: 01kwve0y5s6r0674jt6va8t022
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: reviews
                      attributes:
                        type: object
                        properties:
                          title:
                            type: string
                            example: null
                            nullable: true
                          body:
                            type: string
                            example: 'Nostrum qui commodi incidunt iure.'
                          rating:
                            type: integer
                            example: 5
                          target_type:
                            type: string
                            example: shop
                          target_id:
                            type: string
                            example: 01kwve0y5s6r0674jt6va8t022
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Reviews
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shop_id:
                  type: string
                  description: 'ULID of the shop being reviewed. Provide exactly one of shop_id or item_id.'
                  example: null
                item_id:
                  type: string
                  description: 'ULID of the item being reviewed. Provide exactly one of shop_id or item_id.'
                  example: 01jabcxyz1234567890abcdefg
                title:
                  type: string
                  description: 'Review title.'
                  example: 'Great buying experience'
                  nullable: true
                body:
                  type: string
                  description: 'Review body content.'
                  example: 'Fast shipping and accurate product photos.'
                  nullable: true
                rating:
                  type: integer
                  description: 'Rating from 1 to 5.'
                  example: 5
              required:
                - rating
  '/v1/reviews/{id}':
    get:
      summary: 'Show Review'
      operationId: showReview
      description: 'Fetch a single review by ID.'
      parameters:
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: item, shop, user.'
          example: 'item,shop,user'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: item, shop, user.'
            example: 'item,shop,user'
      responses:
        200:
          description: 'Review details.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: reviews
                    attributes:
                      title: null
                      body: 'Nostrum qui commodi incidunt iure.'
                      rating: 5
                      target_type: shop
                      target_id: 01kwve0y5h2srqhcr3g0qbhk9y
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: reviews
                      attributes:
                        type: object
                        properties:
                          title:
                            type: string
                            example: null
                            nullable: true
                          body:
                            type: string
                            example: 'Nostrum qui commodi incidunt iure.'
                          rating:
                            type: integer
                            example: 5
                          target_type:
                            type: string
                            example: shop
                          target_id:
                            type: string
                            example: 01kwve0y5h2srqhcr3g0qbhk9y
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Review could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Reviews
    patch:
      summary: 'Update Review'
      operationId: updateReview
      description: 'Patch a review by ID.'
      parameters: []
      responses:
        200:
          description: 'Review updated.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: reviews
                    attributes:
                      title: null
                      body: 'Nostrum qui commodi incidunt iure.'
                      rating: 5
                      target_type: shop
                      target_id: 01kwve0y60jx9zbr3pmkwy91y0
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: reviews
                      attributes:
                        type: object
                        properties:
                          title:
                            type: string
                            example: null
                            nullable: true
                          body:
                            type: string
                            example: 'Nostrum qui commodi incidunt iure.'
                          rating:
                            type: integer
                            example: 5
                          target_type:
                            type: string
                            example: shop
                          target_id:
                            type: string
                            example: 01kwve0y60jx9zbr3pmkwy91y0
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/reviews/01ktwg1fhzq1dpagvermfbjzad'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Review could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Reviews
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                shop_id:
                  type: string
                  description: 'Move the review to this shop and clear item_id. Cannot be sent with item_id.'
                  example: 01jabcxyz1234567890abcdefg
                item_id:
                  type: string
                  description: 'Move the review to this item and clear shop_id. Cannot be sent with shop_id.'
                  example: null
                title:
                  type: string
                  description: 'Updated review title.'
                  example: 'Updated buying experience'
                  nullable: true
                body:
                  type: string
                  description: 'Updated review body content.'
                  example: 'Updated review text.'
                  nullable: true
                rating:
                  type: integer
                  description: 'Updated rating from 1 to 5.'
                  example: 4
    delete:
      summary: 'Delete Review'
      operationId: deleteReview
      description: 'Delete a review by ID.'
      parameters: []
      responses:
        204:
          description: 'Review deleted.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Review could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Reviews
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the review.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: review
        description: 'The ULID of the review.'
        example: 01jabcxyz1234567890abcdefg
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/shareables/received':
    get:
      summary: 'List Received Shareables'
      operationId: listReceivedShareables
      description: 'List shareables shared with the authenticated user profile.'
      parameters:
        -
          in: query
          name: 'filter[shareable_type]'
          description: 'Filter by target type.'
          example: shop
          required: false
          schema:
            type: string
            description: 'Filter by target type.'
            example: shop
            enum:
              - shop
              - item
              - collection
        -
          in: query
          name: 'filter[shareable_id]'
          description: 'Filter by target ULID.'
          example: 01ktwg1fhzq1dpagvermfbjzad
          required: false
          schema:
            type: string
            description: 'Filter by target ULID.'
            example: 01ktwg1fhzq1dpagvermfbjzad
        -
          in: query
          name: sort
          description: 'Sort column. Prefix with `-` for descending.'
          example: '-created_at'
          required: false
          schema:
            type: string
            description: 'Sort column. Prefix with `-` for descending.'
            example: '-created_at'
            enum:
              - created_at
              - '-created_at'
              - updated_at
              - '-updated_at'
        -
          in: query
          name: per_page
          description: 'Number of shareables per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of shareables per page (1-100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: shareable, sharedByProfile, sharedWithProfile.'
          example: 'shareable,sharedByProfile'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: shareable, sharedByProfile, sharedWithProfile.'
            example: 'shareable,sharedByProfile'
      responses:
        200:
          description: 'Paginated received shareable list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: shareables
                      attributes:
                        shareable_type: null
                        shareable_id: null
                        shared_by_profile_id: null
                        shared_with_profile_id: null
                        created_at: null
                        updated_at: null
                    -
                      id: ''
                      type: shareables
                      attributes:
                        shareable_type: null
                        shareable_id: null
                        shared_by_profile_id: null
                        shared_with_profile_id: null
                        created_at: null
                        updated_at: null
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: shareables
                        attributes:
                          shareable_type: null
                          shareable_id: null
                          shared_by_profile_id: null
                          shared_with_profile_id: null
                          created_at: null
                          updated_at: null
                      -
                        id: ''
                        type: shareables
                        attributes:
                          shareable_type: null
                          shareable_id: null
                          shared_by_profile_id: null
                          shared_with_profile_id: null
                          created_at: null
                          updated_at: null
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: shareables
                        attributes:
                          type: object
                          properties:
                            shareable_type:
                              type: string
                              example: null
                              nullable: true
                            shareable_id:
                              type: string
                              example: null
                              nullable: true
                            shared_by_profile_id:
                              type: string
                              example: null
                              nullable: true
                            shared_with_profile_id:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: null
                              nullable: true
                            updated_at:
                              type: string
                              example: null
                              nullable: true
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Authenticated user profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Shareables
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/shareables/sent':
    get:
      summary: 'List Sent Shareables'
      operationId: listSentShareables
      description: 'List shareables sent by the authenticated user profile.'
      parameters:
        -
          in: query
          name: 'filter[shareable_type]'
          description: 'Filter by target type.'
          example: shop
          required: false
          schema:
            type: string
            description: 'Filter by target type.'
            example: shop
            enum:
              - shop
              - item
              - collection
        -
          in: query
          name: 'filter[shareable_id]'
          description: 'Filter by target ULID.'
          example: 01ktwg1fhzq1dpagvermfbjzad
          required: false
          schema:
            type: string
            description: 'Filter by target ULID.'
            example: 01ktwg1fhzq1dpagvermfbjzad
        -
          in: query
          name: sort
          description: 'Sort column. Prefix with `-` for descending.'
          example: '-created_at'
          required: false
          schema:
            type: string
            description: 'Sort column. Prefix with `-` for descending.'
            example: '-created_at'
            enum:
              - created_at
              - '-created_at'
              - updated_at
              - '-updated_at'
        -
          in: query
          name: per_page
          description: 'Number of shareables per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of shareables per page (1-100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: shareable, sharedByProfile, sharedWithProfile.'
          example: 'shareable,sharedWithProfile'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: shareable, sharedByProfile, sharedWithProfile.'
            example: 'shareable,sharedWithProfile'
      responses:
        200:
          description: 'Paginated sent shareable list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: shareables
                      attributes:
                        shareable_type: null
                        shareable_id: null
                        shared_by_profile_id: null
                        shared_with_profile_id: null
                        created_at: null
                        updated_at: null
                    -
                      id: ''
                      type: shareables
                      attributes:
                        shareable_type: null
                        shareable_id: null
                        shared_by_profile_id: null
                        shared_with_profile_id: null
                        created_at: null
                        updated_at: null
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: shareables
                        attributes:
                          shareable_type: null
                          shareable_id: null
                          shared_by_profile_id: null
                          shared_with_profile_id: null
                          created_at: null
                          updated_at: null
                      -
                        id: ''
                        type: shareables
                        attributes:
                          shareable_type: null
                          shareable_id: null
                          shared_by_profile_id: null
                          shared_with_profile_id: null
                          created_at: null
                          updated_at: null
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: shareables
                        attributes:
                          type: object
                          properties:
                            shareable_type:
                              type: string
                              example: null
                              nullable: true
                            shareable_id:
                              type: string
                              example: null
                              nullable: true
                            shared_by_profile_id:
                              type: string
                              example: null
                              nullable: true
                            shared_with_profile_id:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: null
                              nullable: true
                            updated_at:
                              type: string
                              example: null
                              nullable: true
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Authenticated user profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Shareables
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/shareables/{id}':
    get:
      summary: 'Show Shareable'
      operationId: showShareable
      description: 'Fetch one shareable if the authenticated user profile is the sender or recipient.'
      parameters:
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: shareable, sharedByProfile, sharedWithProfile.'
          example: 'shareable,sharedByProfile'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: shareable, sharedByProfile, sharedWithProfile.'
            example: 'shareable,sharedByProfile'
      responses:
        200:
          description: 'Shareable details.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: shareables
                    attributes:
                      shareable_type: null
                      shareable_id: null
                      shared_by_profile_id: null
                      shared_with_profile_id: null
                      created_at: null
                      updated_at: null
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: shareables
                      attributes:
                        type: object
                        properties:
                          shareable_type:
                            type: string
                            example: null
                            nullable: true
                          shareable_id:
                            type: string
                            example: null
                            nullable: true
                          shared_by_profile_id:
                            type: string
                            example: null
                            nullable: true
                          shared_with_profile_id:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: null
                            nullable: true
                          updated_at:
                            type: string
                            example: null
                            nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Shareable could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Shareables
    delete:
      summary: 'Delete Shareable'
      operationId: deleteShareable
      description: 'Delete one shareable if the authenticated user profile is the sender or recipient.'
      parameters: []
      responses:
        204:
          description: 'Shareable deleted.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Shareable could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Shareables
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: id
        description: 'The ID of the shareable.'
        example: 16
        required: true
        schema:
          type: integer
      -
        in: path
        name: shareable
        description: 'The shareable ID.'
        example: 1
        required: true
        schema:
          type: integer
  '/v1/me/profiles/{actingProfile_id}/shareables':
    post:
      summary: 'Create Shareable'
      operationId: createShareable
      description: 'Share a shop, item, or collection with a friend profile.'
      parameters: []
      responses:
        201:
          description: 'Shareable created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: shareables
                    attributes:
                      shareable_type: null
                      shareable_id: null
                      shared_by_profile_id: null
                      shared_with_profile_id: null
                      created_at: null
                      updated_at: null
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: shareables
                      attributes:
                        type: object
                        properties:
                          shareable_type:
                            type: string
                            example: null
                            nullable: true
                          shareable_id:
                            type: string
                            example: null
                            nullable: true
                          shared_by_profile_id:
                            type: string
                            example: null
                            nullable: true
                          shared_with_profile_id:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: null
                            nullable: true
                          updated_at:
                            type: string
                            example: null
                            nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Authenticated user profile could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Shareables
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shareable_type:
                  type: string
                  description: 'Shareable target type.'
                  example: shop
                  enum:
                    - shop
                    - item
                    - collection
                shareable_id:
                  type: string
                  description: 'ULID of the target being shared.'
                  example: 01ktwg1fhzq1dpagvermfbjzad
                shared_with_profile_id:
                  type: string
                  description: 'Friend profile ULID receiving the share.'
                  example: 01ktwg1fhzq1dpagvermfbjzae
              required:
                - shareable_type
                - shareable_id
                - shared_with_profile_id
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  /v1/shops:
    get:
      summary: 'List Shops'
      operationId: listShops
      description: 'List shops with filtering, sorting, pagination, and optional relationship includes.'
      parameters:
        -
          in: query
          name: 'filter[search]'
          description: 'Search by name, slug, domain, website URL, or description.'
          example: odd
          required: false
          schema:
            type: string
            description: 'Search by name, slug, domain, website URL, or description.'
            example: odd
        -
          in: query
          name: 'filter[slug]'
          description: 'Filter by exact shop slug.'
          example: odd-egypt
          required: false
          schema:
            type: string
            description: 'Filter by exact shop slug.'
            example: odd-egypt
        -
          in: query
          name: 'filter[is_active]'
          description: 'Filter by active status.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'Filter by active status.'
            example: true
        -
          in: query
          name: 'filter[verified]'
          description: 'Filter by verification status.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'Filter by verification status.'
            example: true
        -
          in: query
          name: 'filter[country_code]'
          description: 'Filter by ISO country code.'
          example: null
          required: false
          schema:
            type: string
            description: 'Filter by ISO country code.'
            example: null
        -
          in: query
          name: 'filter[classification]'
          description: 'Filter by shop classification.'
          example: online_store
          required: false
          schema:
            type: string
            description: 'Filter by shop classification.'
            example: online_store
            enum:
              - online_store
              - local_brand
              - marketplace
              - department_store
              - specialty_store
              - boutique
              - chain_store
              - franchise
        -
          in: query
          name: 'filter[category_id]'
          description: 'Filter by category ULID.'
          example: 01ktwg1fhzq1dpagvermfbjzad
          required: false
          schema:
            type: string
            description: 'Filter by category ULID.'
            example: 01ktwg1fhzq1dpagvermfbjzad
        -
          in: query
          name: 'filter[feature_id]'
          description: 'Filter by shop feature ID.'
          example: null
          required: false
          schema:
            type: integer
            description: 'Filter by shop feature ID.'
            example: null
        -
          in: query
          name: 'filter[ecommerce_provider_id]'
          description: 'Filter by ecommerce provider ID.'
          example: null
          required: false
          schema:
            type: integer
            description: 'Filter by ecommerce provider ID.'
            example: null
        -
          in: query
          name: 'filter[social_platform]'
          description: 'Filter by social profile platform.'
          example: instagram
          required: false
          schema:
            type: string
            description: 'Filter by social profile platform.'
            example: instagram
            enum:
              - facebook
              - instagram
        -
          in: query
          name: 'filter[social_identifier_type]'
          description: 'Filter by social profile identifier type.'
          example: username
          required: false
          schema:
            type: string
            description: 'Filter by social profile identifier type.'
            example: username
            enum:
              - username
              - profile_id
              - url
        -
          in: query
          name: 'filter[social_identifier]'
          description: 'Filter by normalized social profile identifier.'
          example: odd.eg
          required: false
          schema:
            type: string
            description: 'Filter by normalized social profile identifier.'
            example: odd.eg
        -
          in: query
          name: 'filter[scraped_from]'
          description: 'Only shops scraped on or after this date (`Y-m-d`).'
          example: '2026-04-01'
          required: false
          schema:
            type: string
            description: 'Only shops scraped on or after this date (`Y-m-d`).'
            example: '2026-04-01'
        -
          in: query
          name: 'filter[scraped_until]'
          description: 'Only shops scraped on or before this date (`Y-m-d`).'
          example: '2026-04-15'
          required: false
          schema:
            type: string
            description: 'Only shops scraped on or before this date (`Y-m-d`).'
            example: '2026-04-15'
        -
          in: query
          name: sort
          description: 'Sort column. Recommended sorting requires authentication and X-Profile-ID.'
          example: '-created_at'
          required: false
          schema:
            type: string
            description: 'Sort column. Recommended sorting requires authentication and X-Profile-ID.'
            example: '-created_at'
            enum:
              - recommended
              - popularity
              - '-popularity'
              - name
              - '-name'
              - created_at
              - '-created_at'
              - updated_at
              - '-updated_at'
              - verified_at
              - '-verified_at'
              - last_scraped_at
              - '-last_scraped_at'
        -
          in: query
          name: per_page
          description: 'Number of shops per page (1–100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of shops per page (1–100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: country, categories, features.'
          example: 'country,categories'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: country, categories, features.'
            example: 'country,categories'
      responses:
        200:
          description: 'Paginated shop list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: shops
                      attributes:
                        name: 'Bailey Ltd'
                        slug: bailey-ltd
                        description: 'Et fugiat sunt nihil accusantium.'
                        website_url: 'https://okuneva.test'
                        domain: okuneva.test
                        phone: +1-463-622-3498
                        email: marquardt.noah@example.com
                        address: "38862 Ferne Locks Suite 058\nChristianshire, IA 97161"
                        classification: department_store
                        country_code: null
                        region: 'North Demarcusmouth'
                        is_active: true
                        is_verified: false
                        verified_at: null
                        inactive_reason: null
                        social_profiles: []
                        url: null
                        logo_url: null
                        banner_image_url: null
                        shop_image_url: null
                        shop_favicon_url: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                    -
                      id: ''
                      type: shops
                      attributes:
                        name: 'Labadie, Haag and Considine'
                        slug: labadie-haag-and-considine
                        description: 'Eum doloremque id aut libero aliquam veniam corporis.'
                        website_url: 'https://wisoky.test'
                        domain: wisoky.test
                        phone: '(907) 735-1679'
                        email: libby.bradtke@example.com
                        address: "4985 Jacques Lakes Apt. 004\nRoxanneview, GA 41591-5182"
                        classification: marketplace
                        country_code: null
                        region: 'North Zachery'
                        is_active: true
                        is_verified: false
                        verified_at: null
                        inactive_reason: null
                        social_profiles: []
                        url: null
                        logo_url: null
                        banner_image_url: null
                        shop_image_url: null
                        shop_favicon_url: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: shops
                        attributes:
                          name: 'Bailey Ltd'
                          slug: bailey-ltd
                          description: 'Et fugiat sunt nihil accusantium.'
                          website_url: 'https://okuneva.test'
                          domain: okuneva.test
                          phone: +1-463-622-3498
                          email: marquardt.noah@example.com
                          address: "38862 Ferne Locks Suite 058\nChristianshire, IA 97161"
                          classification: department_store
                          country_code: null
                          region: 'North Demarcusmouth'
                          is_active: true
                          is_verified: false
                          verified_at: null
                          inactive_reason: null
                          social_profiles: []
                          url: null
                          logo_url: null
                          banner_image_url: null
                          shop_image_url: null
                          shop_favicon_url: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                      -
                        id: ''
                        type: shops
                        attributes:
                          name: 'Labadie, Haag and Considine'
                          slug: labadie-haag-and-considine
                          description: 'Eum doloremque id aut libero aliquam veniam corporis.'
                          website_url: 'https://wisoky.test'
                          domain: wisoky.test
                          phone: '(907) 735-1679'
                          email: libby.bradtke@example.com
                          address: "4985 Jacques Lakes Apt. 004\nRoxanneview, GA 41591-5182"
                          classification: marketplace
                          country_code: null
                          region: 'North Zachery'
                          is_active: true
                          is_verified: false
                          verified_at: null
                          inactive_reason: null
                          social_profiles: []
                          url: null
                          logo_url: null
                          banner_image_url: null
                          shop_image_url: null
                          shop_favicon_url: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: shops
                        attributes:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'Bailey Ltd'
                            slug:
                              type: string
                              example: bailey-ltd
                            description:
                              type: string
                              example: 'Et fugiat sunt nihil accusantium.'
                            website_url:
                              type: string
                              example: 'https://okuneva.test'
                            domain:
                              type: string
                              example: okuneva.test
                            phone:
                              type: string
                              example: +1-463-622-3498
                            email:
                              type: string
                              example: marquardt.noah@example.com
                            address:
                              type: string
                              example: "38862 Ferne Locks Suite 058\nChristianshire, IA 97161"
                            classification:
                              type: string
                              example: department_store
                            country_code:
                              type: string
                              example: null
                              nullable: true
                            region:
                              type: string
                              example: 'North Demarcusmouth'
                            is_active:
                              type: boolean
                              example: true
                            is_verified:
                              type: boolean
                              example: false
                            verified_at:
                              type: string
                              example: null
                              nullable: true
                            inactive_reason:
                              type: string
                              example: null
                              nullable: true
                            social_profiles:
                              type: array
                              example: []
                            url:
                              type: string
                              example: null
                              nullable: true
                            logo_url:
                              type: string
                              example: null
                              nullable: true
                            banner_image_url:
                              type: string
                              example: null
                              nullable: true
                            shop_image_url:
                              type: string
                              example: null
                              nullable: true
                            shop_favicon_url:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - Shops
      security: []
    post:
      summary: 'Create Shop'
      operationId: createShop
      description: 'Create a new shop record.'
      parameters: []
      responses:
        201:
          description: 'Shop created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: shops
                    attributes:
                      name: 'Price Ltd'
                      slug: price-ltd
                      description: 'Commodi incidunt iure odit.'
                      website_url: 'https://cronin.test'
                      domain: cronin.test
                      phone: 203-867-3351
                      email: nstokes@example.org
                      address: "427 Labadie Curve Suite 170\nLake Micaela, ID 92203"
                      classification: chain_store
                      country_code: null
                      region: 'West Cynthiaberg'
                      is_active: true
                      is_verified: false
                      verified_at: null
                      inactive_reason: null
                      social_profiles: []
                      url: null
                      logo_url: null
                      banner_image_url: null
                      shop_image_url: null
                      shop_favicon_url: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: shops
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Price Ltd'
                          slug:
                            type: string
                            example: price-ltd
                          description:
                            type: string
                            example: 'Commodi incidunt iure odit.'
                          website_url:
                            type: string
                            example: 'https://cronin.test'
                          domain:
                            type: string
                            example: cronin.test
                          phone:
                            type: string
                            example: 203-867-3351
                          email:
                            type: string
                            example: nstokes@example.org
                          address:
                            type: string
                            example: "427 Labadie Curve Suite 170\nLake Micaela, ID 92203"
                          classification:
                            type: string
                            example: chain_store
                          country_code:
                            type: string
                            example: null
                            nullable: true
                          region:
                            type: string
                            example: 'West Cynthiaberg'
                          is_active:
                            type: boolean
                            example: true
                          is_verified:
                            type: boolean
                            example: false
                          verified_at:
                            type: string
                            example: null
                            nullable: true
                          inactive_reason:
                            type: string
                            example: null
                            nullable: true
                          social_profiles:
                            type: array
                            example: []
                          url:
                            type: string
                            example: null
                            nullable: true
                          logo_url:
                            type: string
                            example: null
                            nullable: true
                          banner_image_url:
                            type: string
                            example: null
                            nullable: true
                          shop_image_url:
                            type: string
                            example: null
                            nullable: true
                          shop_favicon_url:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Shops
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Human-friendly shop name.'
                  example: 'Odd Egypt'
                domain:
                  type: string
                  description: 'Primary domain for the shop.'
                  example: oddegypt.com
                slug:
                  type: string
                  description: 'URL slug. Generated from name when omitted.'
                  example: odd-egypt
                  nullable: true
                website_url:
                  type: string
                  description: 'Canonical website URL. Defaults to `https://{domain}` when omitted.'
                  example: 'https://oddegypt.com'
                  nullable: true
                description:
                  type: string
                  description: 'Shop description.'
                  example: 'Independent Egyptian online store.'
                  nullable: true
                phone:
                  type: string
                  description: 'Public shop phone number.'
                  example: '+20 100 000 0000'
                  nullable: true
                email:
                  type: string
                  description: 'Public shop email address.'
                  example: hello@oddegypt.com
                  nullable: true
                address:
                  type: string
                  description: 'Public shop address.'
                  example: 'Cairo, Egypt'
                  nullable: true
                classification:
                  type: string
                  description: 'Shop classification.'
                  example: online_store
                  enum:
                    - online_store
                    - local_brand
                    - marketplace
                    - department_store
                    - specialty_store
                    - boutique
                    - chain_store
                    - franchise
                  nullable: true
                country_code:
                  type: string
                  description: 'ISO 3166-1 alpha-2 country code.'
                  example: EG
                  nullable: true
                country_id:
                  type: integer
                  description: 'Country record ID. Reconciled with `country_code` when both are provided.'
                  example: 1
                  nullable: true
                region:
                  type: string
                  description: 'Shop region or city.'
                  example: Cairo
                  nullable: true
                is_active:
                  type: boolean
                  description: 'Whether the shop is active.'
                  example: true
                verified_at:
                  type: string
                  description: 'Verification timestamp (ISO 8601). Set to mark the shop as manually verified.'
                  example: '2026-04-15T12:00:00+00:00'
                  nullable: true
                favorite:
                  type: boolean
                  description: 'Favorite the created or matched shop for the authenticated user.'
                  example: true
                social_profiles:
                  type: array
                  description: 'Facebook or Instagram profiles for shops without websites.'
                  example:
                    - platform: instagram
                      handle: '@odd.eg'
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        description: 'Social platform.'
                        example: instagram
                        enum:
                          - facebook
                          - instagram
                      handle:
                        type: string
                        description: 'Social handle when known.'
                        example: '@odd.eg'
                        nullable: true
                      url:
                        type: string
                        description: 'Social profile URL, including Facebook profile ID URLs.'
                        example: 'https://www.facebook.com/profile.php?id=100077674242505'
                        nullable: true
                    required:
                      - platform
              required:
                - name
                - domain
  '/v1/shops/{id}':
    get:
      summary: 'Show Shop'
      operationId: showShop
      description: 'Fetch a single shop by ULID.'
      parameters:
        -
          in: query
          name: include
          description: 'Comma-separated relationships to include: country, categories, features.'
          example: 'country,features'
          required: false
          schema:
            type: string
            description: 'Comma-separated relationships to include: country, categories, features.'
            example: 'country,features'
      responses:
        200:
          description: 'Shop details.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: shops
                    attributes:
                      name: "Rempel, Gulgowski and O'Kon"
                      slug: rempel-gulgowski-and-okon
                      description: 'Accusantium harum mollitia modi deserunt aut ab.'
                      website_url: 'https://ernser.test'
                      domain: ernser.test
                      phone: 1-463-692-1881
                      email: wleuschke@example.net
                      address: "1052 Carey Greens\nLefflerhaven, TX 58408-7043"
                      classification: marketplace
                      country_code: null
                      region: Raynormouth
                      is_active: true
                      is_verified: false
                      verified_at: null
                      inactive_reason: null
                      social_profiles: []
                      url: null
                      logo_url: null
                      banner_image_url: null
                      shop_image_url: null
                      shop_favicon_url: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: shops
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: "Rempel, Gulgowski and O'Kon"
                          slug:
                            type: string
                            example: rempel-gulgowski-and-okon
                          description:
                            type: string
                            example: 'Accusantium harum mollitia modi deserunt aut ab.'
                          website_url:
                            type: string
                            example: 'https://ernser.test'
                          domain:
                            type: string
                            example: ernser.test
                          phone:
                            type: string
                            example: 1-463-692-1881
                          email:
                            type: string
                            example: wleuschke@example.net
                          address:
                            type: string
                            example: "1052 Carey Greens\nLefflerhaven, TX 58408-7043"
                          classification:
                            type: string
                            example: marketplace
                          country_code:
                            type: string
                            example: null
                            nullable: true
                          region:
                            type: string
                            example: Raynormouth
                          is_active:
                            type: boolean
                            example: true
                          is_verified:
                            type: boolean
                            example: false
                          verified_at:
                            type: string
                            example: null
                            nullable: true
                          inactive_reason:
                            type: string
                            example: null
                            nullable: true
                          social_profiles:
                            type: array
                            example: []
                          url:
                            type: string
                            example: null
                            nullable: true
                          logo_url:
                            type: string
                            example: null
                            nullable: true
                          banner_image_url:
                            type: string
                            example: null
                            nullable: true
                          shop_image_url:
                            type: string
                            example: null
                            nullable: true
                          shop_favicon_url:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
        404:
          description: 'Shop could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Shops
      security: []
    patch:
      summary: 'Update Shop'
      operationId: updateShop
      description: 'Patch a shop by ULID.'
      parameters: []
      responses:
        200:
          description: 'Shop updated.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: ''
                    type: shops
                    attributes:
                      name: 'Dare Group'
                      slug: dare-group
                      description: 'Odit et et modi.'
                      website_url: 'https://leuschke.test'
                      domain: leuschke.test
                      phone: +1-715-952-7161
                      email: tleuschke@example.net
                      address: "723 Wisoky Passage\nMicaelatown, CA 87335-0574"
                      classification: specialty_store
                      country_code: null
                      region: 'West Gisselle'
                      is_active: true
                      is_verified: false
                      verified_at: null
                      inactive_reason: null
                      social_profiles: []
                      url: null
                      logo_url: null
                      banner_image_url: null
                      shop_image_url: null
                      shop_favicon_url: null
                      created_at: '2026-07-06T10:01:48+00:00'
                      updated_at: '2026-07-06T10:01:48+00:00'
                    links:
                      self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: ''
                      type:
                        type: string
                        example: shops
                      attributes:
                        type: object
                        properties:
                          name:
                            type: string
                            example: 'Dare Group'
                          slug:
                            type: string
                            example: dare-group
                          description:
                            type: string
                            example: 'Odit et et modi.'
                          website_url:
                            type: string
                            example: 'https://leuschke.test'
                          domain:
                            type: string
                            example: leuschke.test
                          phone:
                            type: string
                            example: +1-715-952-7161
                          email:
                            type: string
                            example: tleuschke@example.net
                          address:
                            type: string
                            example: "723 Wisoky Passage\nMicaelatown, CA 87335-0574"
                          classification:
                            type: string
                            example: specialty_store
                          country_code:
                            type: string
                            example: null
                            nullable: true
                          region:
                            type: string
                            example: 'West Gisselle'
                          is_active:
                            type: boolean
                            example: true
                          is_verified:
                            type: boolean
                            example: false
                          verified_at:
                            type: string
                            example: null
                            nullable: true
                          inactive_reason:
                            type: string
                            example: null
                            nullable: true
                          social_profiles:
                            type: array
                            example: []
                          url:
                            type: string
                            example: null
                            nullable: true
                          logo_url:
                            type: string
                            example: null
                            nullable: true
                          banner_image_url:
                            type: string
                            example: null
                            nullable: true
                          shop_image_url:
                            type: string
                            example: null
                            nullable: true
                          shop_favicon_url:
                            type: string
                            example: null
                            nullable: true
                          created_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                          updated_at:
                            type: string
                            example: '2026-07-06T10:01:48+00:00'
                      links:
                        type: object
                        properties:
                          self:
                            type: string
                            example: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Shop could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
        422:
          description: 'Validation failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
      tags:
        - Shops
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Human-friendly shop name.'
                  example: 'Odd Egypt Boutique'
                domain:
                  type: string
                  description: 'Primary domain for the shop.'
                  example: oddegypt.com
                slug:
                  type: string
                  description: 'New URL slug for the shop.'
                  example: odd-egypt-boutique
                  nullable: true
                website_url:
                  type: string
                  description: 'Canonical website URL.'
                  example: 'https://oddegypt.com'
                  nullable: true
                description:
                  type: string
                  description: 'Shop description.'
                  example: 'Updated shop description.'
                  nullable: true
                phone:
                  type: string
                  description: 'Public shop phone number.'
                  example: '+20 100 000 0000'
                  nullable: true
                email:
                  type: string
                  description: 'Public shop email address.'
                  example: hello@oddegypt.com
                  nullable: true
                address:
                  type: string
                  description: 'Public shop address.'
                  example: 'Cairo, Egypt'
                  nullable: true
                classification:
                  type: string
                  description: 'Shop classification.'
                  example: boutique
                  enum:
                    - online_store
                    - local_brand
                    - marketplace
                    - department_store
                    - specialty_store
                    - boutique
                    - chain_store
                    - franchise
                  nullable: true
                country_code:
                  type: string
                  description: 'ISO 3166-1 alpha-2 country code.'
                  example: EG
                  nullable: true
                country_id:
                  type: integer
                  description: 'Country record ID. Reconciled with `country_code` when both are provided.'
                  example: 1
                  nullable: true
                region:
                  type: string
                  description: 'Shop region or city.'
                  example: Alexandria
                  nullable: true
                is_active:
                  type: boolean
                  description: 'Whether the shop is active.'
                  example: true
                verified_at:
                  type: string
                  description: 'Verification timestamp (ISO 8601). Set to mark the shop as manually verified.'
                  example: '2026-04-15T12:00:00+00:00'
                  nullable: true
                social_profiles:
                  type: array
                  description: 'Replacement Facebook or Instagram profiles for the shop.'
                  example:
                    - platform: instagram
                      handle: '@odd.eg'
                  items:
                    type: object
                    properties:
                      platform:
                        type: string
                        description: 'Social platform.'
                        example: instagram
                        enum:
                          - facebook
                          - instagram
                      handle:
                        type: string
                        description: 'Social handle when known.'
                        example: '@odd.eg'
                        nullable: true
                      url:
                        type: string
                        description: 'Social profile URL, including Facebook profile ID URLs.'
                        example: 'https://www.facebook.com/profile.php?id=100077674242505'
                        nullable: true
                    required:
                      - platform
    delete:
      summary: 'Delete Shop'
      operationId: deleteShop
      description: 'Soft delete a shop by ULID.'
      parameters: []
      responses:
        204:
          description: 'Shop deleted.'
          content:
            application/json:
              schema:
                type: object
                nullable: true
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Shop could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - Shops
    parameters:
      -
        in: path
        name: id
        description: 'The ID of the shop.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: shop
        description: 'The ULID of the shop.'
        example: 01ktwg1fhzq1dpagvermfbjzad
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/bookmarked-items':
    get:
      summary: 'List User Bookmarked Items'
      operationId: listUserBookmarkedItems
      description: 'List bookmarked items for the authenticated user.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of bookmarked items per page (1-100).'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of bookmarked items per page (1-100).'
            example: 20
        -
          in: query
          name: include
          description: 'Comma-separated item relationships to include: shop, brand, categories, variants.'
          example: shop
          required: false
          schema:
            type: string
            description: 'Comma-separated item relationships to include: shop, brand, categories, variants.'
            example: shop
      responses:
        200:
          description: 'Bookmarked item list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: items
                      attributes:
                        name: 'Incidunt Iure Odit'
                        slug: incidunt-iure-odit
                        description: 'Et modi ipsum nostrum omnis autem et consequatur.'
                        external_url: null
                        price: 3651.56
                        original_price: null
                        currency: EGP
                        sku: SN-515-RW
                        condition: new
                        stock_level: 13
                        weight: null
                        dimensions: null
                        specifications: null
                        is_available: true
                        is_active: true
                        url: null
                        featured_image_url: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                    -
                      id: ''
                      type: items
                      attributes:
                        name: 'Reiciendis Quia Perspiciatis'
                        slug: reiciendis-quia-perspiciatis
                        description: 'Ducimus corrupti et dolores quia maiores assumenda.'
                        external_url: null
                        price: 689.49
                        original_price: null
                        currency: EGP
                        sku: SG-468-TV
                        condition: new
                        stock_level: 143
                        weight: null
                        dimensions: null
                        specifications: null
                        is_available: true
                        is_active: true
                        url: null
                        featured_image_url: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: items
                        attributes:
                          name: 'Incidunt Iure Odit'
                          slug: incidunt-iure-odit
                          description: 'Et modi ipsum nostrum omnis autem et consequatur.'
                          external_url: null
                          price: 3651.56
                          original_price: null
                          currency: EGP
                          sku: SN-515-RW
                          condition: new
                          stock_level: 13
                          weight: null
                          dimensions: null
                          specifications: null
                          is_available: true
                          is_active: true
                          url: null
                          featured_image_url: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                      -
                        id: ''
                        type: items
                        attributes:
                          name: 'Reiciendis Quia Perspiciatis'
                          slug: reiciendis-quia-perspiciatis
                          description: 'Ducimus corrupti et dolores quia maiores assumenda.'
                          external_url: null
                          price: 689.49
                          original_price: null
                          currency: EGP
                          sku: SG-468-TV
                          condition: new
                          stock_level: 143
                          weight: null
                          dimensions: null
                          specifications: null
                          is_available: true
                          is_active: true
                          url: null
                          featured_image_url: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: items
                        attributes:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'Incidunt Iure Odit'
                            slug:
                              type: string
                              example: incidunt-iure-odit
                            description:
                              type: string
                              example: 'Et modi ipsum nostrum omnis autem et consequatur.'
                            external_url:
                              type: string
                              example: null
                              nullable: true
                            price:
                              type: number
                              example: 3651.56
                            original_price:
                              type: string
                              example: null
                              nullable: true
                            currency:
                              type: string
                              example: EGP
                            sku:
                              type: string
                              example: SN-515-RW
                            condition:
                              type: string
                              example: new
                            stock_level:
                              type: integer
                              example: 13
                            weight:
                              type: string
                              example: null
                              nullable: true
                            dimensions:
                              type: string
                              example: null
                              nullable: true
                            specifications:
                              type: string
                              example: null
                              nullable: true
                            is_available:
                              type: boolean
                              example: true
                            is_active:
                              type: boolean
                              example: true
                            url:
                              type: string
                              example: null
                              nullable: true
                            featured_image_url:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/items/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - 'User Bookmarked Items'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/bookmarked-items/{item_id}':
    post:
      summary: 'Create User Bookmarked Item'
      operationId: createUserBookmarkedItem
      description: 'Bookmark an item for the authenticated user.'
      parameters: []
      responses:
        200:
          description: 'Item was already bookmarked by the user.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Bookmarked item already exists.'
                properties:
                  message:
                    type: string
                    example: 'Bookmarked item already exists.'
        201:
          description: 'Bookmarked item created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Bookmarked item created.'
                properties:
                  message:
                    type: string
                    example: 'Bookmarked item created.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Item could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'User Bookmarked Items'
    delete:
      summary: 'Delete User Bookmarked Item'
      operationId: deleteUserBookmarkedItem
      description: 'Delete an item from the authenticated user bookmarked items.'
      parameters: []
      responses:
        200:
          description: 'Bookmarked item deleted.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Bookmarked item deleted.'
                properties:
                  message:
                    type: string
                    example: 'Bookmarked item deleted.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Item could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'User Bookmarked Items'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: item_id
        description: 'The ULID of the item to bookmark.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/favorite-shops':
    get:
      summary: 'List User Favorite Shops'
      operationId: listUserFavoriteShops
      description: 'List favorite shops for the authenticated user.'
      parameters: []
      responses:
        200:
          description: 'Favorite shop list.'
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: ''
                      type: shops
                      attributes:
                        name: 'Baumbach Ltd'
                        slug: baumbach-ltd
                        description: 'Nostrum omnis autem et consequatur aut.'
                        website_url: 'https://bauch.test'
                        domain: bauch.test
                        phone: 283.476.7809
                        email: jhaag@example.net
                        address: "2127 Verlie Manors\nWest Gisselle, CO 53669"
                        classification: boutique
                        country_code: null
                        region: 'East Nedra'
                        is_active: true
                        is_verified: false
                        verified_at: null
                        inactive_reason: null
                        social_profiles: []
                        url: null
                        logo_url: null
                        banner_image_url: null
                        shop_image_url: null
                        shop_favicon_url: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                    -
                      id: ''
                      type: shops
                      attributes:
                        name: 'Bradtke Group'
                        slug: bradtke-group
                        description: 'Qui repudiandae laboriosam est alias.'
                        website_url: 'https://emmerich.test'
                        domain: emmerich.test
                        phone: 269-915-6037
                        email: moises37@example.com
                        address: "13733 Runolfsson Mall\nMargarettaside, OH 29924"
                        classification: marketplace
                        country_code: null
                        region: Kreigerburgh
                        is_active: true
                        is_verified: false
                        verified_at: null
                        inactive_reason: null
                        social_profiles: []
                        url: null
                        logo_url: null
                        banner_image_url: null
                        shop_image_url: null
                        shop_favicon_url: null
                        created_at: '2026-07-06T10:01:48+00:00'
                        updated_at: '2026-07-06T10:01:48+00:00'
                      links:
                        self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    first: '/?page=1'
                    last: '/?page=1'
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    from: 1
                    last_page: 1
                    links:
                      -
                        url: null
                        label: '&laquo; Previous'
                        page: null
                        active: false
                      -
                        url: '/?page=1'
                        label: '1'
                        page: 1
                        active: true
                      -
                        url: null
                        label: 'Next &raquo;'
                        page: null
                        active: false
                    path: /
                    per_page: 2
                    to: 2
                    total: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: ''
                        type: shops
                        attributes:
                          name: 'Baumbach Ltd'
                          slug: baumbach-ltd
                          description: 'Nostrum omnis autem et consequatur aut.'
                          website_url: 'https://bauch.test'
                          domain: bauch.test
                          phone: 283.476.7809
                          email: jhaag@example.net
                          address: "2127 Verlie Manors\nWest Gisselle, CO 53669"
                          classification: boutique
                          country_code: null
                          region: 'East Nedra'
                          is_active: true
                          is_verified: false
                          verified_at: null
                          inactive_reason: null
                          social_profiles: []
                          url: null
                          logo_url: null
                          banner_image_url: null
                          shop_image_url: null
                          shop_favicon_url: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                      -
                        id: ''
                        type: shops
                        attributes:
                          name: 'Bradtke Group'
                          slug: bradtke-group
                          description: 'Qui repudiandae laboriosam est alias.'
                          website_url: 'https://emmerich.test'
                          domain: emmerich.test
                          phone: 269-915-6037
                          email: moises37@example.com
                          address: "13733 Runolfsson Mall\nMargarettaside, OH 29924"
                          classification: marketplace
                          country_code: null
                          region: Kreigerburgh
                          is_active: true
                          is_verified: false
                          verified_at: null
                          inactive_reason: null
                          social_profiles: []
                          url: null
                          logo_url: null
                          banner_image_url: null
                          shop_image_url: null
                          shop_favicon_url: null
                          created_at: '2026-07-06T10:01:48+00:00'
                          updated_at: '2026-07-06T10:01:48+00:00'
                        links:
                          self: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: ''
                        type:
                          type: string
                          example: shops
                        attributes:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'Baumbach Ltd'
                            slug:
                              type: string
                              example: baumbach-ltd
                            description:
                              type: string
                              example: 'Nostrum omnis autem et consequatur aut.'
                            website_url:
                              type: string
                              example: 'https://bauch.test'
                            domain:
                              type: string
                              example: bauch.test
                            phone:
                              type: string
                              example: 283.476.7809
                            email:
                              type: string
                              example: jhaag@example.net
                            address:
                              type: string
                              example: "2127 Verlie Manors\nWest Gisselle, CO 53669"
                            classification:
                              type: string
                              example: boutique
                            country_code:
                              type: string
                              example: null
                              nullable: true
                            region:
                              type: string
                              example: 'East Nedra'
                            is_active:
                              type: boolean
                              example: true
                            is_verified:
                              type: boolean
                              example: false
                            verified_at:
                              type: string
                              example: null
                              nullable: true
                            inactive_reason:
                              type: string
                              example: null
                              nullable: true
                            social_profiles:
                              type: array
                              example: []
                            url:
                              type: string
                              example: null
                              nullable: true
                            logo_url:
                              type: string
                              example: null
                              nullable: true
                            banner_image_url:
                              type: string
                              example: null
                              nullable: true
                            shop_image_url:
                              type: string
                              example: null
                              nullable: true
                            shop_favicon_url:
                              type: string
                              example: null
                              nullable: true
                            created_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                            updated_at:
                              type: string
                              example: '2026-07-06T10:01:48+00:00'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              example: 'http://bazaarspot-api.test/v1/shops/01ktwg1fhzq1dpagvermfbjzad'
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: '/?page=1'
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      links:
                        type: array
                        example:
                          - url: null
                            label: '&laquo; Previous'
                            page: null
                            active: false
                          - url: '/?page=1'
                            label: '1'
                            page: 1
                            active: true
                          - url: null
                            label: 'Next &raquo;'
                            page: null
                            active: false
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              example: null
                              nullable: true
                            label:
                              type: string
                              example: '&laquo; Previous'
                            page:
                              type: string
                              example: null
                              nullable: true
                            active:
                              type: boolean
                              example: false
                      path:
                        type: string
                        example: /
                      per_page:
                        type: integer
                        example: 2
                      to:
                        type: integer
                        example: 2
                      total:
                        type: integer
                        example: 2
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
      tags:
        - 'User Favorite Shops'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
  '/v1/me/profiles/{actingProfile_id}/favorite-shops/{shop_id}':
    post:
      summary: 'Create User Favorite Shop'
      operationId: createUserFavoriteShop
      description: 'Favorite a shop for the authenticated user.'
      parameters: []
      responses:
        200:
          description: 'Shop was already favorited by the user.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Favorite shop already exists.'
                properties:
                  message:
                    type: string
                    example: 'Favorite shop already exists.'
        201:
          description: 'Favorite shop created.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Favorite shop created.'
                properties:
                  message:
                    type: string
                    example: 'Favorite shop created.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Shop could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'User Favorite Shops'
    delete:
      summary: 'Delete User Favorite Shop'
      operationId: deleteUserFavoriteShop
      description: 'Delete a shop from the authenticated user favorite shops.'
      parameters: []
      responses:
        200:
          description: 'Favorite shop deleted.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Favorite shop deleted.'
                properties:
                  message:
                    type: string
                    example: 'Favorite shop deleted.'
        401:
          description: 'Authentication failed.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
        403:
          description: 'Token is missing the required ability.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Forbidden.
                properties:
                  message:
                    type: string
                    example: Forbidden.
        404:
          description: 'Shop could not be found.'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not Found.'
                properties:
                  message:
                    type: string
                    example: 'Not Found.'
      tags:
        - 'User Favorite Shops'
    parameters:
      -
        in: path
        name: actingProfile_id
        description: 'The ID of the actingProfile.'
        example: architecto
        required: true
        schema:
          type: string
      -
        in: path
        name: shop_id
        description: 'The ULID of the shop to favorite.'
        example: 01AN4Z07BY79KA1307SR9X4MV3
        required: true
        schema:
          type: string
