openapi: 3.1.0
info:
  title: Gravatar Public API
  version: 3.0.0
  description: Gravatar's public API endpoints
  contact:
    name: Gravatar
    url: 'https://gravatar.com'
servers:
  - url: 'https://api.gravatar.com/v3'
    description: Production server
tags:
  - name: profiles
    description: Operations about user profiles
  - name: avatars
    description: Operations about user avatars
  - name: qr-code
    description: Operations about QR codes
  - name: experimental
    description: Experimental operations that might be subject to change. Use with caution.
components:
  headers:
    X-RateLimit-Limit:
      description: The number of allowed requests in the current period.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: The number of remaining requests in the current period.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: >-
        The time at which the current rate limit period resets, in Unix
        timestamp format.
      schema:
        type: integer
  schemas:
    Avatar:
      type: object
      description: An avatar that the user has already uploaded to their Gravatar account.
      required:
        - image_id
        - image_url
        - rating
        - updated_date
        - alt_text
      properties:
        image_id:
          type: string
          description: Unique identifier for the image.
          examples:
            - 38be15a98a2bbc40df69172a2a8349
        image_url:
          type: string
          description: Image URL
          format: uri
          examples:
            - >-
              https://gravatar.com/userimage/252014526/d38bele5a98a2bbc40df69172a2a8348.jpeg
        rating:
          type: string
          description: Rating associated with the image.
          enum:
            - G
            - PG
            - R
            - X
        alt_text:
          type: string
          description: Alternative text description of the image.
          examples:
            - >-
              Gravatar's avatar image. Gravatar is a service for providing
              globally unique avatars.
        selected:
          type: boolean
          description: >-
            Whether the image is currently selected as the provided selected
            email's avatar.
          examples:
            - true
        updated_date:
          type: string
          format: date-time
          description: Date and time when the image was last updated.
          pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$'
          examples:
            - '2021-10-01T12:00:00Z'
    AvatarRating:
      type: string
      description: Rating associated with the image.
      enum:
        - G
        - PG
        - R
        - X
    Link:
      type: object
      description: A link the user has added to their profile.
      required:
        - label
        - url
      properties:
        label:
          type: string
          description: The label for the link.
          examples:
            - Personal Website
        url:
          type: string
          format: uri
          description: The URL to the link.
          examples:
            - 'https://example.com'
    Interest:
      type: object
      description: An interest the user has added to their profile.
      required:
        - id
        - name
      properties:
        id:
          type: integer
          description: The unique identifier for the interest.
          examples:
            - 1
        name:
          type: string
          description: >-
            The name of the interest as originally defined (most often in
            English).
          examples:
            - photography
    CryptoWalletAddress:
      type: object
      description: A crypto currency wallet address the user accepts.
      required:
        - label
        - address
      properties:
        label:
          type: string
          description: The label for the crypto currency.
          examples:
            - ETH
        address:
          type: string
          description: The wallet address for the crypto currency.
          examples:
            - 0xABC123...
    VerifiedAccount:
      type: object
      description: A verified account on a user's profile.
      required:
        - service_type
        - service_label
        - service_icon
        - url
        - is_hidden
      properties:
        service_type:
          type: string
          description: The type of the service.
          examples:
            - tumblr
        service_label:
          type: string
          description: The name of the service.
          examples:
            - Tumblr
        service_icon:
          type: string
          description: The URL to the service's icon.
          format: uri
          examples:
            - 'https://gravatar.com/icons/tumblr-alt.svg'
        url:
          type: string
          description: The URL to the user's profile on the service.
          format: uri
          examples:
            - 'https://example.tumblr.com/'
        is_hidden:
          type: boolean
          description: Whether the verified account is hidden from the user's profile.
          examples:
            - false
    GalleryImage:
      type: object
      description: A gallery image a user has uploaded.
      required:
        - url
      properties:
        url:
          type: string
          description: The URL to the image.
          format: uri
          examples:
            - >-
              https://0.gravatar.com/userimage/5/04bbd674f72c703f6335e2e7a00acc9a
        alt_text:
          type: string
          description: The image alt text.
          examples:
            - A beautiful sunset
    Language:
      type: object
      description: >-
        The languages the user knows. This is only provided in authenticated API
        requests.
      required:
        - code
        - name
        - is_primary
        - order
      properties:
        code:
          type: string
          description: The language code.
          examples:
            - en
        name:
          type: string
          description: The language name.
          examples:
            - English
        is_primary:
          type: boolean
          description: Whether the language is the user's primary language.
          examples:
            - true
        order:
          type: integer
          description: The order of the language in the user's profile.
          examples:
            - 1
    Profile:
      type: object
      description: A user's profile information.
      required:
        - hash
        - display_name
        - profile_url
        - avatar_url
        - avatar_alt_text
        - location
        - description
        - job_title
        - company
        - verified_accounts
        - pronunciation
        - pronouns
      properties:
        user_id:
          type: integer
          description: >-
            The unique user ID. NOTE: This is only provided in OAuth2
            authenticated requests.
          examples:
            - 1234567890
        user_login:
          type: string
          description: >-
            The user's login name. NOTE: This is only provided in OAuth2
            authenticated requests.
          examples:
            - alex
        hash:
          type: string
          description: The SHA256 hash of the user's primary email address.
          examples:
            - 31c5543c1734d25c7206f5fd591525d0295bec6fe84ff82f946a34fe970a1e66
        display_name:
          type: string
          description: >-
            The user's display name. This is the name that is displayed on their
            profile.
          examples:
            - Alex Morgan
        profile_url:
          type: string
          description: The full URL for the user's profile.
          format: uri
          examples:
            - 'https://gravatar.com/example'
        avatar_url:
          type: string
          format: uri
          description: The URL for the user's avatar image if it has been set.
          examples:
            - >-
              https://0.gravatar.com/avatar/33252cd1f33526af53580fcb1736172f06e6716f32afdd1be19ec3096d15dea5
        avatar_alt_text:
          type: string
          description: The alt text for the user's avatar image if it has been set.
          examples:
            - >-
              Alex Morgan's avatar image. Alex is smiling and standing in beside
              a large dog who is looking up at Alex.
        location:
          type: string
          description: The user's location.
          examples:
            - 'New York, USA'
        description:
          type: string
          description: The about section on a user's profile.
          examples:
            - I like playing hide and seek.
        job_title:
          type: string
          description: The user's job title.
          examples:
            - Landscape Architect
        company:
          type: string
          description: The user's current company's name.
          examples:
            - ACME Corp
        verified_accounts:
          type: array
          description: >-
            A list of verified accounts the user has added to their profile.
            This is limited to a max of 4 in unauthenticated requests.
          items:
            $ref: '#/components/schemas/VerifiedAccount'
        pronunciation:
          type: string
          description: The phonetic pronunciation of the user's name.
          examples:
            - Al-ex Mor-gan
        pronouns:
          type: string
          description: The pronouns the user uses.
          examples:
            - She/They
        timezone:
          type: string
          description: >-
            The timezone the user has. This is only provided in authenticated
            API requests.
          examples:
            - Europe/Bratislava
        languages:
          type: array
          description: >-
            The languages the user knows. This is only provided in authenticated
            API requests.
          items:
            $ref: '#/components/schemas/Language'
        first_name:
          type: string
          description: >-
            User's first name. This is only provided in authenticated API
            requests.
          examples:
            - Alex
        last_name:
          type: string
          description: >-
            User's last name. This is only provided in authenticated API
            requests.
          examples:
            - Morgan
        is_organization:
          type: boolean
          description: >-
            Whether user is an organization. This is only provided in
            authenticated API requests.
          examples:
            - false
        header_image:
          type: string
          description: The header image used in the main profile card.
          examples:
            - >-
              url('https://gravatar.com/userimage/209234789/cdebd0ed415kfa2g562ba5c34b1570c2')
              no-repeat 50% 1% / 100%
        background_color:
          type: string
          description: The profile background color.
          examples:
            - 'rgb(33, 0, 166)'
            - 'linear-gradient(135deg, rgb(2, 3, 129) 0%, rgb(40, 116, 252) 100%)'
        links:
          type: array
          description: >-
            A list of links the user has added to their profile. This is only
            provided in authenticated API requests.
          items:
            $ref: '#/components/schemas/Link'
        interests:
          type: array
          description: >-
            A list of interests the user has added to their profile. This is
            only provided in authenticated API requests.
          items:
            $ref: '#/components/schemas/Interest'
        payments:
          type: object
          required:
            - links
            - crypto_wallets
          description: >-
            The user's public payment information. This is only provided in
            authenticated API requests.
          properties:
            links:
              type: array
              description: A list of payment URLs the user has added to their profile.
              items:
                $ref: '#/components/schemas/Link'
            crypto_wallets:
              type: array
              description: A list of crypto currencies the user accepts.
              items:
                $ref: '#/components/schemas/CryptoWalletAddress'
        contact_info:
          type: object
          description: >-
            The user's contact information. This is only available if the user
            has chosen to make it public. This is only provided in authenticated
            API requests.
          properties:
            home_phone:
              type: string
              description: The user's home phone number.
              examples:
                - +1-555-555-0100
            work_phone:
              type: string
              description: The user's work phone number.
              examples:
                - +1-555-555-0101
            cell_phone:
              type: string
              description: The user's cell phone number.
              examples:
                - +1-555-555-0102
            email:
              type: string
              description: >-
                The user's email address as provided on the contact section of
                the profile. Might differ from their account emails.
              format: email
              examples:
                - alex@example.com
            contact_form:
              type: string
              description: The URL to the user's contact form.
              format: uri
              examples:
                - 'https://example.com/contact-me'
            calendar:
              type: string
              description: The URL to the user's calendar.
              format: uri
              examples:
                - 'https://example.com/calendar'
        gallery:
          type: array
          description: >-
            Additional images a user has uploaded. This is only provided in
            authenticated API requests.
          items:
            $ref: '#/components/schemas/GalleryImage'
        number_verified_accounts:
          type: integer
          description: >-
            The number of verified accounts the user has added to their profile.
            This count includes verified accounts the user is hiding from their
            profile. This is only provided in authenticated API requests.
          examples:
            - 3
        last_profile_edit:
          type:
            - string
            - 'null'
          nullable: true
          description: >-
            The date and time (UTC) the user last edited their profile. This is
            only provided in authenticated API requests.
          format: date-time
          pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$'
          examples:
            - '2021-10-01T12:00:00Z'
        registration_date:
          type:
            - string
            - 'null'
          nullable: true
          description: >-
            The date the user registered their account. This is only provided in
            authenticated API requests.
          format: date-time
          pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$'
          examples:
            - '2021-10-01T12:00:00Z'
    AssociatedResponse:
      type: object
      required:
        - associated
      properties:
        associated:
          type: boolean
          description: Whether the entity is associated with the account.
          examples:
            - true
    Error:
      type: object
      description: An error response from the API.
      properties:
        error:
          type: string
          description: The error message
        code:
          type: string
          description: The error code for the error message
      required:
        - error
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Bearer token to authenticate the request. Full profile information is
        only available in authenticated requests.
    oauth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'https://public-api.wordpress.com/oauth2/authorize'
          scopes: {}
      description: WordPress OAuth token to authenticate the request.
  responses:
    not_authorized:
      description: Not Authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              value:
                error: You are not authorized to perform this action
    insufficient_scope:
      description: Insufficient Scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            insufficient_scope:
              value:
                code: insufficient_scope
                error: >-
                  The provided token does not contain the required scope for
                  this request.
    rate_limit_exceeded:
      description: Rate Limit Exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rate_limit_exceeded:
              value:
                error: Rate limit exceeded
                code: rate_limit_exceeded
paths:
  '/profiles/{profileIdentifier}':
    get:
      summary: Get profile by identifier
      description: Returns a profile by the given identifier.
      tags:
        - profiles
      operationId: getProfileById
      parameters:
        - name: profileIdentifier
          in: path
          required: true
          description: >-
            This can either be an SHA256 hash of an email address or profile URL
            slug.
          schema:
            type: string
      security:
        - apiKey: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '404':
          description: Profile not found
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '429':
          description: Rate limit exceeded
          $ref: '#/components/responses/rate_limit_exceeded'
        '500':
          description: Internal server error
  '/profiles/{profileIdentifier}/inferred-interests':
    get:
      summary: Get inferred interests for a profile given their identifier
      description: >-
        Returns a list of inferred interests based on known and public
        information about the profile.
      tags:
        - experimental
      operationId: getProfileInferredInterestsById
      parameters:
        - name: profileIdentifier
          in: path
          required: true
          description: >-
            This can either be an SHA256 hash of an email address or profile URL
            slug.
          schema:
            type: string
      security:
        - apiKey: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                description: A list of interests the user might (or might not) like.
                items:
                  $ref: '#/components/schemas/Interest'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '404':
          description: Profile not found
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '429':
          description: Rate limit exceeded
          $ref: '#/components/responses/rate_limit_exceeded'
        '500':
          description: Internal server error
  /profiles/search/by-verified-account:
    get:
      summary: Search for profiles by verified account username
      description: >-
        Searches Gravatar profiles that have a verified account with the given
        username. Optionally filter by the service (e.g., 'github', 'twitter').
        See `/verified-accounts/services` for supported ID values. Results are
        paginated.
      tags:
        - experimental
      operationId: searchProfilesByVerifiedAccount
      parameters:
        - name: username
          in: query
          required: true
          description: The username used on the verified third-party service.
          schema:
            type: string
        - name: service
          in: query
          required: false
          description: >-
            The service to limit search to (e.g., 'github', 'twitter'). See
            `/verified-accounts/services` for supported IDs.
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Page number of results to retrieve.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          required: false
          description: 'Number of results per page. Defaults to 20, maximum 50.'
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
      security:
        - apiKey: []
      responses:
        '200':
          description: List of matching profiles
          content:
            application/json:
              schema:
                type: object
                required:
                  - profiles
                  - total_pages
                properties:
                  profiles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile'
                  total_pages:
                    type: integer
                    description: Total number of pages available.
                    examples:
                      - 5
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '400':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/not_authorized'
        '429':
          $ref: '#/components/responses/rate_limit_exceeded'
        '500':
          description: Internal server error
  /verified-accounts/services:
    get:
      summary: Get list of services supported as verified accounts
      description: >-
        Returns the list of verified account services with their ID and
        human-readable labels.
      tags:
        - experimental
      operationId: getVerifiedAccountServices
      responses:
        '200':
          description: Supported verified account services
          content:
            application/json:
              schema:
                type: object
                required:
                  - services
                properties:
                  services:
                    type: array
                    description: List of supported verified account services.
                    items:
                      type: object
                      required:
                        - id
                        - label
                      properties:
                        id:
                          type: string
                          description: The identifier for the service.
                          examples:
                            - github
                            - twitter
                            - tumblr
                            - mastodon
                        label:
                          type: string
                          description: The human-readable label for the service.
                          examples:
                            - GitHub
                            - Twitter
                            - Tumblr
                            - Mastodon
                examples:
                  - services:
                      - id: github
                        label: GitHub
                      - id: twitter
                        label: Twitter
                      - id: tumblr
                        label: Tumblr
                      - id: mastodon
                        label: Mastodon
        '500':
          description: Internal server error
  '/qr-code/{sha256_hash}':
    get:
      summary: Get QR code for an email address' profile
      description: Returns a QR code for an email address by the given SHA256 hash.
      tags:
        - qr-code
      operationId: getQrCodeBySha256Hash
      parameters:
        - name: sha256_hash
          in: path
          required: true
          description: The SHA256 hash of the email address or profile URL slug.
          schema:
            type: string
        - name: size
          in: query
          required: false
          description: The size of the QR code.
          schema:
            type: integer
        - name: version
          in: query
          required: false
          description: The version of the QR code.
          schema:
            type: string
        - name: utm_medium
          in: query
          required: false
          description: >-
            The medium of the UTM parameters. Appended to the URL in the QR
            code.
          schema:
            type: string
        - name: utm_campaign
          in: query
          required: false
          description: >-
            The campaign of the UTM parameters. Appended to the URL in the QR
            code.
          schema:
            type: string
        - name: type
          in: query
          required: false
          description: >-
            The type of center icon to display ('user' for avatar, 'gravatar'
            for logo, 'none' for no icon).
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Gravatar-Profile-Status:
              description: >-
                The status of the profile. Possible values: 'enabled',
                'disabled', 'not-found'
              schema:
                type: string
                examples:
                  - enabled
                  - disabled
                  - not-found
          content:
            image/png:
              schema:
                type: string
                format: binary
        '429':
          description: Rate limit exceeded
          $ref: '#/components/responses/rate_limit_exceeded'
        '500':
          description: Internal server error
  /me/profile:
    get:
      summary: Get profile information for the authenticated user
      description: >-
        Returns the information available for the authenticated user. It's
        equivalent to the full profile information available in the
        `/profiles/{profileIdentifier}` endpoint.
      tags:
        - profiles
      operationId: getProfile
      security:
        - oauth: []
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/Profile'
        '401':
          description: Not Authorized
          $ref: '#/components/responses/not_authorized'
        '403':
          description: Insufficient Scope
          $ref: '#/components/responses/insufficient_scope'
        '404':
          description: Profile is disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                disabled:
                  value:
                    error: Profile is disabled
                    code: disabled
    patch:
      summary: Update profile information for the authenticated user
      description: >-
        Updates the profile information for the authenticated user. Only a
        subset of `Profile` fields are available for update. Partial updates are
        supported, so only the provided fields will be updated. To unset a
        field, set it explicitly to an empty string.
      tags:
        - profiles
      operationId: updateProfile
      security:
        - oauth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                The subset of data available for update. Field names match the
                ones in `Profile`. Only the provided fields will be updated.
              properties:
                first_name:
                  type: string
                  description: The user's first name.
                  examples:
                    - Alex
                last_name:
                  type: string
                  description: The user's last name.
                  examples:
                    - Morgan
                display_name:
                  type: string
                  description: >-
                    The user's display name. This is the name that is displayed
                    on their profile.
                  examples:
                    - Alex Morgan
                description:
                  type: string
                  description: The about section on a user's profile.
                  examples:
                    - I like playing hide and seek.
                pronunciation:
                  type: string
                  description: The phonetic pronunciation of the user's name.
                  examples:
                    - Al-ex Mor-gan
                pronouns:
                  type: string
                  description: The pronouns the user uses.
                  examples:
                    - She/They
                location:
                  type: string
                  description: The user's location.
                  examples:
                    - 'New York, USA'
                job_title:
                  type: string
                  description: The user's job title.
                  examples:
                    - Landscape Architect
                company:
                  type: string
                  description: The user's current company's name.
                  examples:
                    - ACME Corp
                cell_phone:
                  type: string
                  description: The user's cell phone number.
                  examples:
                    - '+1234567890'
                contact_email:
                  type: string
                  description: The user's contact email address.
                  examples:
                    - alex@example.com
                hidden_contact_info:
                  type: boolean
                  description: >-
                    Whether the user's contact information is hidden on their
                    profile.
                  examples:
                    - true
      responses:
        '200':
          description: Profile updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not Authorized
          $ref: '#/components/responses/not_authorized'
        '403':
          description: Insufficient Scope
          $ref: '#/components/responses/insufficient_scope'
        '404':
          description: Profile is disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                disabled:
                  value:
                    error: Profile is disabled
                    code: disabled
  /me/associated-email:
    get:
      summary: Check if the email is associated with the authenticated user
      description: >-
        Checks if the provided email address is associated with the
        authenticated user.
      tags:
        - profiles
      operationId: associatedEmail
      security:
        - oauth: []
      parameters:
        - name: email_hash
          in: query
          required: true
          description: The hash of the email address to check.
          schema:
            type: string
      responses:
        '200':
          description: The email is associated with the authenticated user
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/AssociatedResponse'
        '401':
          description: Not Authorized
          $ref: '#/components/responses/not_authorized'
        '403':
          description: Insufficient Scope
          $ref: '#/components/responses/insufficient_scope'
  /me/avatars:
    get:
      summary: List avatars
      description: Retrieves a list of available avatars for the authenticated user.
      tags:
        - avatars
      operationId: getAvatars
      security:
        - oauth: []
      parameters:
        - name: selected_email_hash
          in: query
          description: >-
            The SHA256 hash of the email address used to determine which avatar
            is selected. The 'selected' attribute in the avatar list will be set
            to 'true' for the avatar associated with this email.
          schema:
            type: string
            default: ''
      responses:
        '200':
          description: Successful retrieval of avatars
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Avatar'
        '401':
          description: Not Authorized
          $ref: '#/components/responses/not_authorized'
        '403':
          description: Insufficient Scope
          $ref: '#/components/responses/insufficient_scope'
    post:
      summary: Upload new avatar image
      description: Uploads a new avatar image for the authenticated user.
      tags:
        - avatars
      operationId: uploadAvatar
      security:
        - oauth: []
      parameters:
        - name: selected_email_hash
          in: query
          description: >-
            The SHA256 hash of email. If provided, the uploaded image will be
            selected as the avatar for this email.
          required: false
          schema:
            type: string
        - name: select_avatar
          in: query
          description: >-
            Determines if the uploaded image should be set as the avatar for the
            email. If not passed, the image is only selected as the email's
            avatar if no previous avatar has been set. Accepts '1'/'true' to
            always set the avatar or '0'/'false' to never set the avatar.
          required: false
          schema:
            type:
              - boolean
              - 'null'
            default: null
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: The avatar image file
              required:
                - image
      responses:
        '200':
          description: Avatar uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Avatar'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                uncropped_image:
                  value:
                    error: Only square images are accepted
                    code: uncropped_image
                unsupported_image:
                  value:
                    error: Unsupported image type
                    code: unsupported_image
        '401':
          description: Not Authorized
          $ref: '#/components/responses/not_authorized'
        '403':
          description: Insufficient Scope
          $ref: '#/components/responses/insufficient_scope'
  '/me/avatars/{imageHash}':
    delete:
      summary: Delete avatar
      description: Deletes a specific avatar for the authenticated user.
      tags:
        - avatars
      operationId: deleteAvatar
      security:
        - oauth: []
      parameters:
        - name: imageHash
          in: path
          required: true
          description: The hash of the avatar to delete.
          schema:
            type: string
      responses:
        '200':
          description: Avatar deleted successfully
        '401':
          description: Not Authorized
          $ref: '#/components/responses/not_authorized'
        '403':
          description: Insufficient Scope
          $ref: '#/components/responses/insufficient_scope'
        '404':
          description: Avatar not found
    patch:
      summary: Update avatar data
      description: Updates the avatar data for a given avatar for the authenticated user.
      tags:
        - avatars
      operationId: updateAvatar
      security:
        - oauth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: >-
                The avatar data to update. Partial updates are supported, so
                only the provided fields will be updated.
              properties:
                rating:
                  description: Rating associated with the image.
                  $ref: '#/components/schemas/AvatarRating'
                alt_text:
                  type: string
                  description: Alternative text description of the image.
                  examples:
                    - >-
                      Gravatar's avatar image. Gravatar is a service for
                      providing globally unique avatars.
              required: []
      parameters:
        - name: imageHash
          in: path
          required: true
          description: The hash of the avatar to update.
          schema:
            type: string
      responses:
        '200':
          description: Avatar updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Avatar'
        '401':
          description: Not Authorized
          $ref: '#/components/responses/not_authorized'
        '403':
          description: Insufficient Scope
          $ref: '#/components/responses/insufficient_scope'
        '404':
          description: Avatar not found
  '/me/avatars/{imageId}/email':
    post:
      summary: Set avatar for the hashed email
      description: Sets the avatar for the provided email hash.
      tags:
        - avatars
      parameters:
        - name: imageId
          in: path
          description: Image ID of the avatar to set as the provided hashed email avatar.
          required: true
          schema:
            type: string
      operationId: setEmailAvatar
      requestBody:
        description: Avatar selection details
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email_hash:
                  type: string
                  description: The email SHA256 hash to set the avatar for.
                  examples:
                    - >-
                      31c5543c1734d25c7206f5fd591525d0295bec6fe84ff82f946a34fe970a1e66
              required:
                - email_hash
      security:
        - oauth: []
      responses:
        '200':
          description: Avatar successfully set
        '401':
          description: Not Authorized
          $ref: '#/components/responses/not_authorized'
        '403':
          description: Insufficient Scope
          $ref: '#/components/responses/insufficient_scope'