openapi: 3.1.0
info:
  title: Gravatar Public avatars profiles 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
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
  /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'
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:
    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
    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:
    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.
    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.