openapi: 3.1.0
info:
  title: Gravatar Public avatars experimental 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: experimental
  description: Experimental operations that might be subject to change. Use with caution.
paths:
  /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
components:
  headers:
    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
    X-RateLimit-Limit:
      description: The number of allowed requests in the current period.
      schema:
        type: integer
  schemas:
    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
    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
    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
    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
    Interest:
      type: object
      description: An interest the user has added to their profile.
      required:
      - id
      - name
      - slug
      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
        slug:
          type: string
          description: The slug representing the interest by combining id and its normalized name.
          examples:
          - 1-photography
    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%
        hide_default_header_image:
          type: boolean
          description: Whether to hide the default header image
          examples:
          - false
        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'
        section_visibility:
          type: object
          description: The visibility of the user's profile sections.
          properties:
            hidden_contact_info:
              type: boolean
              description: Whether the user's contact info section is hidden.
            hidden_feeds:
              type: boolean
              description: Whether the user's feeds section is hidden.
            hidden_links:
              type: boolean
              description: Whether the user's links section is hidden.
            hidden_interests:
              type: boolean
              description: Whether the user's interests section is hidden.
            hidden_wallet:
              type: boolean
              description: Whether the user's wallet section is hidden.
            hidden_photos:
              type: boolean
              description: Whether the user's photo gallery section is hidden.
            hidden_verified_accounts:
              type: boolean
              description: Whether the user's verified accounts section is hidden.
    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...
    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
  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
    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
  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.