openapi: 3.0.0
info:
  description: "Get basic website information from any given URL. You can find out more about
    LinkPreview at [https://www.linkpreview.net](https://www.linkpreview.net). Get you API key for free at [https://my.linkpreview.net](https://my.linkpreview.net)."
  version: 1.0.0
  title: LinkPreview API
  termsOfService: https://www.linkpreview.net/terms/
  contact:
    email: info@linkpreview.net
servers:
  - url: https://api.linkpreview.net     
  - url: http://api.linkpreview.net
externalDocs:
  description: Online documentation
  url: https://docs.linkpreview.net
paths:
  /:    
    get:
      tags:
        - API Request
      summary: Get link preview
      description: "Get a link preview"
      operationId: getlinkpreview
      security:
        - api_key: []
      parameters:
        - name: q
          in: query
          description: URL to inspect
          required: true
          schema:
            type: string
          example: https://google.com
        - name: key
          in: query
          description: Your API Key
          required: true          
          schema:
            type: string
          example: 123456
        - name: fields
          in: query
          description: Comma-separated list of fields to return. See [fields](https://docs.linkpreview.net/#default-and-additional-fields).
          required: false          
          schema:
            type: string       
          example: image_x, icon_type, locale          
      responses:
        "200":
          description: successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"     
        "400":
          description: Generic error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"  
              example: 
                title: ''
                description: Generic error
                image: ''
                url: ''                 
                error: 400                
        "401":
          description: Cannot verify API access key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"     
              example: 
                title: ''
                description: Cannot verify API access key
                image: ''
                url: ''                 
                error: 401                  
        "403":
          description: Invalid or blank API access key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"     
              example: 
                title: ''
                description: Invalid or blank API access key
                image: ''
                url: ''                 
                error: 403                  
        "423":
          description: Forbidden by robots.txt - the requested website does not allow us to access this page. See [robots exclusion standard](https://en.wikipedia.org/wiki/Robots_exclusion_standard).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"     
              example: 
                title: ''
                description: Forbidden by robots.txt - the requested website does not allow us to access this page
                image: ''
                url: ''                 
                error: 423                  
        "425":
          description: Invalid response status code (with the actual response code we got from the remote server)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"     
              example: 
                title: ''
                description: Invalid response status code (501)
                image: ''
                url: ''                 
                error: 425                  
        "426":
          description: Too many requests per second on a single domain
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"     
              example: 
                title: ''
                description: Too many requests per second on a single domain
                image: ''
                url: ''                 
                error: 426                  
        "429":
          description: Too many requests / rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"    
              example: 
                title: ''
                description: Too many requests / rate limit exceeded
                image: ''
                url: ''                 
                error: 429                  
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: key
      in: query
      description: Get you free API key [here](https://my.linkpreview.net).   
  schemas:
    Response:
      type: object
      required:
        - title
        - description
        - image
        - url
      properties:
        title:
          type: string
          description: Website title. Available on all plans.
          example: Google          
        description:
          type: string
          description: Description summary. Available on all plans.
          example: Search webpages, images, videos and more.          
        image:
          type: string
          description: Preview image URL. Available on all plans.
          example: https://www.google.com/images/logo.png          
        url:
          type: string
          description: Destination URL. Available on all plans.
          example: https://www.google.com            
    ExtendedResponse:
      type: object
      required:
        - title
        - description
        - image
        - url
      properties:
        title:
          type: string
          description: Website title. Available on all plans.
          example: Google          
        description:
          type: string
          description: Description summary. Available on all plans.
          example: Search webpages, images, videos and more.          
        image:
          type: string
          description: Preview image URL. Available on all plans.
          example: https://www.google.com/images/logo.png          
        url:
          type: string
          description: Destination URL. Available on all plans.
          example: https://www.google.com          
        canonical:
          type: string
          description: Canonical or "preferred" version of a web page. Defaults to blank "" if not found. Available on Basic, Pro, Enterprise.
          example: https://www.google.com/en
        locale:
          type: string
          description: Web page's locale formatted as language_TERRITORY. Defaults to "en_US" if not found. You can use this to detect RTL languages or to display other language-specific elements. Available on Basic, Pro, Enterprise.
          example: en_GB      
        site_name:
          type: string
          description: Short domain name formatted as top_level_domain+1. Use this to display short name instead of a full link. Available on Basic, Pro, Enterprise.
          example: google.com           
        image_x:
          type: integer
          format: int64
          description: Image width in pixels. See [image processing](https://docs.linkpreview.net/#image-processing-and-validation). Available on Pro, Enterprise.
          example: 600           
        image_y:
          type: integer
          format: int64
          description: Image height in pixels. See [image processing](https://docs.linkpreview.net/#image-processing-and-validation). Available on Pro, Enterprise.
          example: 400     
        image_size:
          type: integer
          format: int64
          description: Image size in bytes. See [image processing](https://docs.linkpreview.net/#image-processing-and-validation). Available on Pro, Enterprise.
          example: 643252              
        image_type:
          type: string
          description: Image MIME content type. Available on Pro, Enterprise.
          example: image/jpeg              
        icon:
          type: string
          description: Website icon URL, also known as favicon. Available on Pro, Enterprise.
          example: https://www.google.com/favicon.ico   
        icon_x:
          type: integer
          format: int64
          description: Website icon width in pixels.. Available on Pro, Enterprise.
          example: 50         
        icon_y:
          type: integer
          format: int64
          description: Website icon height in pixels.. Available on Pro, Enterprise.
          example: 50  
        icon_size:
          type: integer
          format: int64
          description: Website icon size in bytes. Available on Pro, Enterprise.
          example: 48322              
        icon_type:
          type: string
          description: Website icon MIME content type. Available on Pro, Enterprise.
          example: image/x-icon             
        image_key:
          type: string
          description: Image S3 key. Used to generate URL to the image at Amazon S3 bucket. Self-Hosted only.
          example: cdn/37814cb53005b72397c6646b340d71            
        icon_key:
          type: string
          description: Website icon S3 key. Used to generate URL to the image at Amazon S3 bucket. Self-Hosted only.
          example: cdn/26c28ec312391a13003a33b0013393            
    Error:
      type: object
      required:
        - title
        - description
        - image
        - url
        - error
      properties:
        title:
          type: string
          example: ''
        description:
          type: string
          description: Error Description
          example: Invalid or blank API access key
        image:
          type: string
          example: ''          
        url:
          type: string
          example: ''          
        error:
          type: integer
          format: int64
          description: Error Code
          example: 401          

