openapi: 3.0.3
info:
  title: Imgur API
  version: '3.0'
  description: >-
    Imgur is an online image and album hosting platform. The Imgur API (v3) is a RESTful
    HTTP/JSON API that exposes the platform — uploading, retrieving, voting, commenting,
    galleries, accounts, and tags. Anonymous reads/writes are supported with a Client-ID,
    and per-user actions require OAuth2 access tokens.
  contact:
    name: Imgur API Support
    url: https://help.imgur.com/
  license:
    name: Imgur API Terms
    url: https://imgur.com/tos
servers:
  - url: https://api.imgur.com
    description: Imgur API root
tags:
  - name: Auth
    description: OAuth2 token issuance and refresh.
  - name: Image
    description: Image upload, retrieval, deletion, favorite, and update operations.
  - name: Album
    description: Album creation, retrieval, and image-management operations.
  - name: Gallery
    description: Public gallery listing, voting, sharing, and reporting.
  - name: Comment
    description: Comments on gallery items.
  - name: Account
    description: Account-scoped data: profile, images, albums, favorites, settings, notifications.
  - name: Tags
    description: Tag-based gallery browsing and tagging of gallery items.
  - name: Memegen
    description: Meme generation and meme defaults.
  - name: Notification
    description: User notification retrieval and dismissal.
  - name: Topic
    description: Topic listings and topic galleries.
paths:
  /oauth2/authorize:
    get:
      tags: [Auth]
      summary: Authorize User
      operationId: authorizeUser
      description: Begin the OAuth2 authorization-code or token grant flow.
      parameters:
        - name: client_id
          in: query
          required: true
          schema: { type: string }
        - name: response_type
          in: query
          required: true
          schema: { type: string, enum: [code, token, pin] }
        - name: state
          in: query
          schema: { type: string }
      responses:
        '302':
          description: Redirect To Configured Callback With Code Or Token.
  /oauth2/token:
    post:
      tags: [Auth]
      summary: Issue Access Token
      operationId: issueAccessToken
      description: Exchange an authorization code, refresh token, or PIN for an access token.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [client_id, client_secret, grant_type]
              properties:
                client_id: { type: string }
                client_secret: { type: string }
                grant_type:
                  type: string
                  enum: [authorization_code, refresh_token, pin]
                code: { type: string }
                refresh_token: { type: string }
                pin: { type: string }
      responses:
        '200':
          description: New Access Token Issued.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AccessToken' }

  /3/image:
    post:
      tags: [Image]
      summary: Upload Image
      operationId: uploadImage
      description: Upload an image (binary, base64, or URL).
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image: { type: string, format: binary }
                type: { type: string, enum: [file, base64, url] }
                title: { type: string }
                description: { type: string }
                album: { type: string }
      responses:
        '200':
          description: Image Uploaded.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BasicResponse' }
  /3/image/{imageHash}:
    get:
      tags: [Image]
      summary: Get Image
      operationId: getImage
      parameters:
        - $ref: '#/components/parameters/ImageHash'
      responses:
        '200':
          description: Image Metadata.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BasicResponse' }
    delete:
      tags: [Image]
      summary: Delete Image
      operationId: deleteImage
      parameters:
        - $ref: '#/components/parameters/ImageHash'
      responses:
        '200':
          description: Image Deleted.
    post:
      tags: [Image]
      summary: Update Image Information
      operationId: updateImage
      parameters:
        - $ref: '#/components/parameters/ImageHash'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                title: { type: string }
                description: { type: string }
      responses:
        '200':
          description: Image Updated.
  /3/image/{imageHash}/favorite:
    post:
      tags: [Image]
      summary: Favorite Image
      operationId: favoriteImage
      parameters:
        - $ref: '#/components/parameters/ImageHash'
      responses:
        '200':
          description: Favorite Toggled.

  /3/album/{albumHash}:
    get:
      tags: [Album]
      summary: Get Album
      operationId: getAlbum
      parameters:
        - $ref: '#/components/parameters/AlbumHash'
      responses:
        '200':
          description: Album Metadata.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BasicResponse' }
    delete:
      tags: [Album]
      summary: Delete Album
      operationId: deleteAlbum
      parameters:
        - $ref: '#/components/parameters/AlbumHash'
      responses:
        '200':
          description: Album Deleted.
    put:
      tags: [Album]
      summary: Update Album
      operationId: updateAlbum
      parameters:
        - $ref: '#/components/parameters/AlbumHash'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                title: { type: string }
                description: { type: string }
                ids: { type: array, items: { type: string } }
                privacy: { type: string, enum: [public, hidden, secret] }
                layout: { type: string, enum: [blog, grid, horizontal, vertical] }
                cover: { type: string }
      responses:
        '200':
          description: Album Updated.
  /3/album:
    post:
      tags: [Album]
      summary: Create Album
      operationId: createAlbum
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                title: { type: string }
                description: { type: string }
                ids: { type: array, items: { type: string } }
                privacy: { type: string, enum: [public, hidden, secret] }
      responses:
        '200':
          description: Album Created.
  /3/album/{albumHash}/images:
    get:
      tags: [Album]
      summary: Get Album Images
      operationId: getAlbumImages
      parameters:
        - $ref: '#/components/parameters/AlbumHash'
      responses:
        '200':
          description: Image List.
  /3/album/{albumHash}/favorite:
    post:
      tags: [Album]
      summary: Favorite Album
      operationId: favoriteAlbum
      parameters:
        - $ref: '#/components/parameters/AlbumHash'
      responses:
        '200':
          description: Favorite Toggled.

  /3/gallery/{section}/{sort}/{window}/{page}:
    get:
      tags: [Gallery]
      summary: Get Gallery
      operationId: getGallery
      parameters:
        - name: section
          in: path
          required: true
          schema: { type: string, enum: [hot, top, user] }
        - name: sort
          in: path
          required: true
          schema: { type: string, enum: [viral, top, time, rising] }
        - name: window
          in: path
          required: true
          schema: { type: string, enum: [day, week, month, year, all] }
        - name: page
          in: path
          required: true
          schema: { type: integer, default: 0 }
      responses:
        '200':
          description: Gallery Items.
  /3/gallery/search:
    get:
      tags: [Gallery]
      summary: Search Gallery
      operationId: searchGallery
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
        - name: sort
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Search Results.
  /3/gallery/image/{galleryHash}:
    get:
      tags: [Gallery]
      summary: Get Gallery Image
      operationId: getGalleryImage
      parameters:
        - name: galleryHash
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Gallery Image.
  /3/gallery/album/{galleryHash}:
    get:
      tags: [Gallery]
      summary: Get Gallery Album
      operationId: getGalleryAlbum
      parameters:
        - name: galleryHash
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Gallery Album.
  /3/gallery/{galleryHash}/vote/{vote}:
    post:
      tags: [Gallery]
      summary: Vote On Gallery Item
      operationId: voteGalleryItem
      parameters:
        - name: galleryHash
          in: path
          required: true
          schema: { type: string }
        - name: vote
          in: path
          required: true
          schema: { type: string, enum: [up, down, veto] }
      responses:
        '200':
          description: Vote Recorded.
  /3/gallery/{galleryHash}/report:
    post:
      tags: [Gallery]
      summary: Report Gallery Item
      operationId: reportGalleryItem
      parameters:
        - name: galleryHash
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Report Submitted.
  /3/gallery/image:
    post:
      tags: [Gallery]
      summary: Submit Image To Gallery
      operationId: submitImageToGallery
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string }
                topic: { type: string }
                terms: { type: integer, enum: [0, 1] }
      responses:
        '200':
          description: Image Submitted.

  /3/comment/{commentId}:
    get:
      tags: [Comment]
      summary: Get Comment
      operationId: getComment
      parameters:
        - name: commentId
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Comment Details.
    delete:
      tags: [Comment]
      summary: Delete Comment
      operationId: deleteComment
      parameters:
        - name: commentId
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Comment Deleted.
  /3/comment:
    post:
      tags: [Comment]
      summary: Create Comment
      operationId: createComment
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [image_id, comment]
              properties:
                image_id: { type: string }
                comment: { type: string }
                parent_id: { type: string }
      responses:
        '200':
          description: Comment Created.
  /3/comment/{commentId}/reply:
    post:
      tags: [Comment]
      summary: Reply To Comment
      operationId: replyToComment
      parameters:
        - name: commentId
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [image_id, comment]
              properties:
                image_id: { type: string }
                comment: { type: string }
      responses:
        '200':
          description: Reply Posted.
  /3/comment/{commentId}/vote/{vote}:
    post:
      tags: [Comment]
      summary: Vote On Comment
      operationId: voteOnComment
      parameters:
        - name: commentId
          in: path
          required: true
          schema: { type: integer }
        - name: vote
          in: path
          required: true
          schema: { type: string, enum: [up, down] }
      responses:
        '200':
          description: Vote Recorded.

  /3/account/{username}:
    get:
      tags: [Account]
      summary: Get Account
      operationId: getAccount
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Account Profile.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BasicResponse' }
  /3/account/{username}/images:
    get:
      tags: [Account]
      summary: Get Account Images
      operationId: getAccountImages
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Image List.
  /3/account/{username}/albums:
    get:
      tags: [Account]
      summary: Get Account Albums
      operationId: getAccountAlbums
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Album List.
  /3/account/{username}/comments:
    get:
      tags: [Account]
      summary: Get Account Comments
      operationId: getAccountComments
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Comment List.
  /3/account/{username}/favorites:
    get:
      tags: [Account]
      summary: Get Account Favorites
      operationId: getAccountFavorites
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Favorite List.
  /3/account/{username}/gallery_favorites:
    get:
      tags: [Account]
      summary: Get Gallery Favorites
      operationId: getAccountGalleryFavorites
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Gallery Favorite List.
  /3/account/{username}/submissions:
    get:
      tags: [Account]
      summary: Get Account Submissions
      operationId: getAccountSubmissions
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Submission List.
  /3/account/{username}/settings:
    get:
      tags: [Account]
      summary: Get Account Settings
      operationId: getAccountSettings
      parameters:
        - $ref: '#/components/parameters/Username'
      responses:
        '200':
          description: Settings.
    put:
      tags: [Account]
      summary: Update Account Settings
      operationId: updateAccountSettings
      parameters:
        - $ref: '#/components/parameters/Username'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                bio: { type: string }
                public_images: { type: boolean }
                messaging_enabled: { type: boolean }
                album_privacy: { type: string }
                accepted_gallery_terms: { type: boolean }
                username: { type: string }
                show_mature: { type: boolean }
                newsletter_subscribed: { type: boolean }
      responses:
        '200':
          description: Settings Updated.
  /3/account/me/notifications:
    get:
      tags: [Account, Notification]
      summary: Get Account Notifications
      operationId: getAccountNotifications
      responses:
        '200':
          description: Notification List.
  /3/notification/{notificationId}:
    get:
      tags: [Notification]
      summary: Get Notification
      operationId: getNotification
      parameters:
        - name: notificationId
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Notification Details.
    post:
      tags: [Notification]
      summary: Mark Notification Viewed
      operationId: markNotificationViewed
      parameters:
        - name: notificationId
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Notification Marked Viewed.

  /3/tags:
    get:
      tags: [Tags]
      summary: Get Default Tags
      operationId: getDefaultTags
      responses:
        '200':
          description: Default Tag List.
  /3/gallery/t/{tagName}:
    get:
      tags: [Tags]
      summary: Get Tag Gallery
      operationId: getTagGallery
      parameters:
        - name: tagName
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Tag Gallery.
  /3/gallery/t/{tagName}/{galleryHash}:
    get:
      tags: [Tags]
      summary: Get Tag Gallery Item
      operationId: getTagGalleryItem
      parameters:
        - name: tagName
          in: path
          required: true
          schema: { type: string }
        - name: galleryHash
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Tag Gallery Item.

  /3/memegen/defaults:
    get:
      tags: [Memegen]
      summary: Get Meme Defaults
      operationId: getMemeDefaults
      responses:
        '200':
          description: Default Meme List.

  /3/topics/defaults:
    get:
      tags: [Topic]
      summary: Get Default Topics
      operationId: getDefaultTopics
      responses:
        '200':
          description: Default Topic List.
  /3/topics/{topicId}/{sort}/{window}/{page}:
    get:
      tags: [Topic]
      summary: Get Topic Gallery
      operationId: getTopicGallery
      parameters:
        - name: topicId
          in: path
          required: true
          schema: { type: integer }
        - name: sort
          in: path
          required: true
          schema: { type: string, enum: [viral, top, time] }
        - name: window
          in: path
          required: true
          schema: { type: string, enum: [day, week, month, year, all] }
        - name: page
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Topic Gallery.

  /3/credits:
    get:
      tags: [Account]
      summary: Get Rate Limit Credits
      operationId: getRateLimitCredits
      description: Return remaining client and user credits.
      responses:
        '200':
          description: Credit Status.

components:
  parameters:
    ImageHash:
      name: imageHash
      in: path
      required: true
      description: The image's seven-character hash (e.g. "AbCdEfG").
      schema: { type: string }
    AlbumHash:
      name: albumHash
      in: path
      required: true
      description: The album's seven-character hash.
      schema: { type: string }
    Username:
      name: username
      in: path
      required: true
      description: Account username, or "me" for the authenticated user.
      schema: { type: string }
  securitySchemes:
    ClientId:
      type: apiKey
      in: header
      name: Authorization
      description: "Anonymous access. Header value: `Client-ID <CLIENT_ID>`."
    OAuth2:
      type: oauth2
      description: Per-user OAuth2 authorization.
      flows:
        authorizationCode:
          authorizationUrl: https://api.imgur.com/oauth2/authorize
          tokenUrl: https://api.imgur.com/oauth2/token
          scopes: {}
  schemas:
    BasicResponse:
      type: object
      properties:
        data:
          description: Operation-specific payload.
        success:
          type: boolean
        status:
          type: integer
    AccessToken:
      type: object
      properties:
        access_token: { type: string }
        refresh_token: { type: string }
        expires_in: { type: integer }
        token_type: { type: string }
        account_id: { type: integer }
        account_username: { type: string }
    Image:
      type: object
      properties:
        id: { type: string }
        title: { type: string, nullable: true }
        description: { type: string, nullable: true }
        datetime: { type: integer }
        type: { type: string }
        animated: { type: boolean }
        width: { type: integer }
        height: { type: integer }
        size: { type: integer }
        views: { type: integer }
        bandwidth: { type: integer }
        deletehash: { type: string }
        section: { type: string, nullable: true }
        link: { type: string }
        nsfw: { type: boolean, nullable: true }
        is_album: { type: boolean }
    Album:
      type: object
      properties:
        id: { type: string }
        title: { type: string, nullable: true }
        description: { type: string, nullable: true }
        datetime: { type: integer }
        cover: { type: string, nullable: true }
        cover_width: { type: integer }
        cover_height: { type: integer }
        account_url: { type: string, nullable: true }
        account_id: { type: integer, nullable: true }
        privacy: { type: string, enum: [public, hidden, secret] }
        layout: { type: string, enum: [blog, grid, horizontal, vertical] }
        views: { type: integer }
        link: { type: string }
        images_count: { type: integer }
        images:
          type: array
          items: { $ref: '#/components/schemas/Image' }
    Comment:
      type: object
      properties:
        id: { type: integer }
        image_id: { type: string }
        comment: { type: string }
        author: { type: string }
        author_id: { type: integer }
        on_album: { type: boolean }
        album_cover: { type: string, nullable: true }
        ups: { type: integer }
        downs: { type: integer }
        points: { type: number }
        datetime: { type: integer }
        parent_id: { type: integer }
        deleted: { type: boolean }
        vote: { type: string, nullable: true }
        platform: { type: string, nullable: true }
        children:
          type: array
          items: { $ref: '#/components/schemas/Comment' }
    GalleryItem:
      type: object
      properties:
        id: { type: string }
        title: { type: string }
        description: { type: string, nullable: true }
        datetime: { type: integer }
        cover: { type: string, nullable: true }
        account_url: { type: string }
        account_id: { type: integer }
        privacy: { type: string }
        layout: { type: string }
        views: { type: integer }
        link: { type: string }
        ups: { type: integer }
        downs: { type: integer }
        points: { type: integer }
        score: { type: integer }
        is_album: { type: boolean }
        vote: { type: string, nullable: true }
        favorite: { type: boolean }
        nsfw: { type: boolean }
        comment_count: { type: integer }
        topic: { type: string, nullable: true }
        topic_id: { type: integer, nullable: true }
        tags:
          type: array
          items: { $ref: '#/components/schemas/Tag' }
    Account:
      type: object
      properties:
        id: { type: integer }
        url: { type: string }
        bio: { type: string, nullable: true }
        avatar: { type: string, nullable: true }
        cover: { type: string, nullable: true }
        reputation: { type: number }
        reputation_name: { type: string }
        created: { type: integer }
        pro_expiration: { type: integer, nullable: true }
        user_follow:
          type: object
          properties:
            status: { type: boolean }
        is_blocked: { type: boolean }
    Tag:
      type: object
      properties:
        name: { type: string }
        display_name: { type: string }
        followers: { type: integer }
        total_items: { type: integer }
        following: { type: boolean }
        background_hash: { type: string }
        thumbnail_hash: { type: string, nullable: true }
        accent: { type: string, nullable: true }
        background_is_animated: { type: boolean }
        thumbnail_is_animated: { type: boolean }
        is_promoted: { type: boolean }
        description: { type: string }
        logo_hash: { type: string, nullable: true }
        logo_destination_url: { type: string, nullable: true }
    Notification:
      type: object
      properties:
        id: { type: integer }
        account_id: { type: integer }
        viewed: { type: boolean }
        content:
          type: object
    RateLimitCredits:
      type: object
      properties:
        UserLimit: { type: integer }
        UserRemaining: { type: integer }
        UserReset: { type: integer }
        ClientLimit: { type: integer }
        ClientRemaining: { type: integer }
security:
  - ClientId: []
  - OAuth2: []