swagger: "2.0"
info:
  description: "This is the API to interact with [Blit](https://blitapp.com/), a service to schedule screenshots and get them delivered automatically to your inbox or your cloud.\n\n To use the API, you need to generate an API key from your account. This API key is required for all API calls. It can be sent with the **API-Key** header, or with the query parameter **key**."
  version: "1.0.0"
  title: "Blit"
  termsOfService: "https://blitapp.com/privacypolicy/"
  contact:
    email: "support@blitapp.com"
  license:
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"
host: "blitapp.com"
basePath: "/api"
tags:
- name: "ScheduledCapture"
  description: "Manipulate scheduled captures"
- name: "Web Capture"
  description: "Run a scheduled capture"
  externalDocs:
    description: "Check our blog for more info"
    url: "https://bit.ly/3rFUqWv"
- name: "CaptureHistory"
  description: "Access captures ran"
- name: "App"
  description: "Manage Blit Apps"
  externalDocs:
    description: "Check our blog for more info"
    url: "https://bit.ly/3IoALkr"
- name: "Key"
  description: "Manage API keys"
schemes:
- "https"
security:
  - api_key: []
  - key: []
paths:
  /scheduledcapture:
    get:
      tags:
      - "ScheduledCapture"
      summary: "Get all scheduled captures"
      description: "Retrieve all scheduled captures for your account."
      produces:
      - "application/json"
      responses:
        "400":
          description: "Invalid request"
        "401":
          description: "Authentication failed"
        "200":
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/ScheduledCapture"
    post:
      tags:
      - "ScheduledCapture"
      summary: "Create a new scheduled capture"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "ScheduledCapture object to be created"
        required: true
        schema:
          $ref: "#/definitions/ScheduledCapture"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: Scheduled  capture was created
          schema:
            $ref: "#/definitions/ScheduledCapture"

  /scheduledcapture/{id}:
    put:
      tags:
      - "ScheduledCapture"
      summary: "Update an existing scheduled capture"
      description: ""
      operationId: "scheduledCaptureId"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "ID of scheduled capture to update"
        required: true
        type: "string"
        format: "uuid"
      - in: "body"
        name: "body"
        description: "New scheduled capture properties"
        required: true
        schema:
          $ref: "#/definitions/ScheduledCapture"
      responses:
        "200":
          description: Capture updated
          schema:
            type: array
            description: "Number of captures updated, [0] or [1]"
            items:
              type: integer
              default: 1
              example: 1
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
    get:
      tags:
      - "ScheduledCapture"
      summary: "Retrieve an existing scheduled capture"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "ID of scheduled capture to retrieve"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: definition of the scheduledCapture
          schema:
            $ref: "#/definitions/ScheduledCapture"
    delete:
      tags:
      - "ScheduledCapture"
      summary: "Delete a scheduled capture"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "ID of scheduled capture to delete"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "200":
          description: Capture deleted
          schema:
            type: array
            description: "Number of captures deleted, [0] or [1]"
            items:
              type: integer
              default: 1
              example: 1
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"

  /scheduledcapture/multiple/all:
    put:
      tags:
      - "ScheduledCapture"
      summary: "Update multiple scheduled capture"
      description: ""
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Update scheduled captures"
        required: true
        schema:
          type: "array"
          items:
            $ref: "#/definitions/ScheduledCapture"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/ScheduledCapture"

  /scheduledcapture/{id}/pause:
    put:
      tags:
      - "ScheduledCapture"
      summary: "Pause a scheduled capture"
      description: ""
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "ID of scheduled capture to pause"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "200":
          description: Capture paused
          schema:
            type: array
            description: "Number of captures paused, [0] or [1]"
            items:
              type: integer
              default: 1
              example: 1
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"

  /scheduledcapture/{id}/resume:
    put:
      tags:
      - "ScheduledCapture"
      summary: "Resume a scheduled capture"
      description: ""
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "ID of scheduled capture to resume"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "200":
          description: Capture resumed
          schema:
            type: array
            description: "Number of captures resumed, [0] or [1]"
            items:
              type: integer
              default: 1
              example: 1
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"

  /scheduledcapture/{id}/duplicate:
    put:
      tags:
      - "ScheduledCapture"
      summary: "Duplicate a scheduled capture"
      description: ""
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "ID of scheduled capture to duplicate"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: definition of the scheduledcapture with the new ID
          schema:
            $ref: "#/definitions/ScheduledCapture"

  /scheduledcapture/test/external:
    put:
      tags:
      - "ScheduledCapture"
      summary: "Retrieve the list of URLs from a RSS feed or Sitemap"
      description: ""
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - name: "url"
        in: "query"
        description: "URL of the RSS feed or Sitemap to check"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: definition of the scheduledcapture with the new ID
          schema:
            type: array
            items:
              type: string
              format: uri
              description: list of URLs retrieved
              example: "https://browshot.com/"


  /webcapture/capture/{id}:
    get:
      tags:
      - "WebCapture"
      summary: "Run a scheduled web capture"
      description: ""
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "ID of scheduled capture to run"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "Successful operation"
          schema:
            type: "object"
            properties:
              status:
                type: string
                example: success
                default: success

  /capturehistory:
    get:
      tags:
      - "CaptureHistory"
      summary: "Get your entire history, page by page"
      description: ""
      produces:
      - "application/json"
      parameters:
      - name: "captureId"
        in: "query"
        description: "Get history for a specific scheduled capture"
        required: false
        type: "string"
        format: "uuid"
      - name: "pageIndex"
        in: "query"
        description: "Get history for a page number"
        required: false
        type: "integer"
        default: 0
      - name: "startDate"
        in: "query"
        description: "Get history from a specific date: year-month-day hour:minute:second.millisecond (example: 2020-04-25 07:00:00.000)"
        required: false
        type: "string"
      - name: "endDate"
        in: "query"
        description: "Get history up to a specific date: year-month-day hour:minute:second.millisecond (example: 2020-05-25 06:59:59.999)"
        required: false
        type: "string"
      - name: "tags"
        in: "query"
        description: "Lis of tags, as an array (example: [\"homepage\",\"Browshot\"])"
        required: false
        type: "string"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/CaptureHistory"

  /capturehistory/{scheduledCaptureId}:
    get:
      tags:
      - "CaptureHistory"
      summary: "Get history for a scheduled capture, page by page"
      description: ""
      produces:
      - "application/json"
      parameters:
      - name: "scheduledCaptureId"
        in: "path"
        required: true
        type: "string"
        format: "uuid"
      - name: "pageIndex"
        in: "query"
        description: "Get history for a page number"
        required: false
        type: "integer"
        default: 0
      - name: "pageSize"
        in: "query"
        description: "Number of items per page"
        required: false
        type: "integer"
        default: 10
      - name: "startDate"
        in: "query"
        description: "Get history from a specific date: year-month-day hour:minute:second.millisecond (example: 2020-04-25 07:00:00.000)"
        required: false
        type: "string"
      - name: "endDate"
        in: "query"
        description: "Get history up to a specific date: year-month-day hour:minute:second.millisecond (example: 2020-05-25 06:59:59.999)"
        required: false
        type: "string"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "successful operation"
          schema:
            $ref: "#/definitions/CaptureHistory"

  /capturehistory/image/{fileId}:
    get:
      tags:
      - "CaptureHistory"
      summary: "Retrieve a screenshot"
      description: ""
      produces:
      - "image/png"
      - "image/jpeg"
      parameters:
      - name: "fileId"
        in: "path"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "The screenshot"

  /capturehistory/image/thumbnail/{scheduledCaptureId}:
    get:
      tags:
      - "CaptureHistory"
      summary: "Retrieve the latest thumbnail for a scheduled capture"
      description: ""
      produces:
      - "image/png"
      - "image/jpeg"
      parameters:
      - name: "scheduledCaptureId"
        in: "path"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "The thumbnail"

  /apps/all:
    get:
      tags:
      - "App"
      summary: "Retrieve all your Apps"
      description: ""
      produces:
      - "application/json"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "List of Apps"
          schema:
            type: array
            items:
              $ref: "#/definitions/App"

  /apps/app/{appId}:
    get:
      tags:
      - "App"
      summary: "Retrieve a single App"
      description: ""
      produces:
      - "application/json"
      parameters:
      - name: "appId"
        in: "path"
        required: true
        type: "string"
        format: "uuid"
        description: "App ID"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "an App"
          schema:
              $ref: "#/definitions/App"
    delete:
      tags:
      - "App"
      summary: "Delete an App"
      description: ""
      produces:
      - "application/json"
      parameters:
      - name: "appId"
        in: "path"
        required: true
        type: "string"
        format: "uuid"
        description: "App ID"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "Successful operation"
          schema:
            type: array
            description: "Number of Apps deleted, [0] or [1]"
            items:
              type: integer
              default: 1
              example: 1
    put:
      tags:
      - "App"
      summary: "Update an App"
      description: ""
      produces:
      - "application/json"
      parameters:
      - name: "appId"
        in: "path"
        required: true
        type: "string"
        format: "uuid"
        description: "App ID"
      - in: "body"
        name: "body"
        description: "New App properties"
        required: true
        schema:
          $ref: "#/definitions/App"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "Successful operation"
          schema:
            type: array
            description: "Number of Apps updated, [0] or [1]"
            items:
              type: integer
              default: 1
              example: 1

  /apps/app:
    post:
      tags:
      - "App"
      summary: "Create a new App"
      description: ""
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "New App properties"
        required: true
        schema:
          $ref: "#/definitions/App"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "The App created"
          schema:
              $ref: "#/definitions/App"

  /apps/app/test/verify:
    put:
      tags:
      - "App"
      summary: "Create a new App"
      description: ""
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "The App to verify"
        required: true
        schema:
          $ref: "#/definitions/App"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "Verification was done"
          schema:
            type: array
            description: "[true, ''] if successful, [false, 'error message] if failed"
            items:
              type: boolean

  /keys:
    post:
      tags:
      - "Key"
      summary: "Create a new API key"
      description: ""
      produces:
      - "application/json"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "API key created"
          schema:
            $ref: "#/definitions/Key"
    get:
      tags:
      - "Key"
      summary: "Get all API keys"
      description: ""
      produces:
      - "application/json"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "API keys retrieved"
          schema:
            type: array
            items:
              $ref: "#/definitions/Key"

  /keys/{key}:
    delete:
      tags:
      - "Key"
      summary: "Delete an API key"
      description: ""
      produces:
      - "application/json"
      parameters:
      - name: "key"
        in: "path"
        required: true
        type: "string"
        description: "API key value to delete"
      responses:
        "400":
          description: "Bad request"
        "401":
          description: "Authentication failed"
        "200":
          description: "API key deleted.\n\n**Note**: API keys are actually disabled, not deleted, to make sure keys with the same value are not created later by accident."
          schema:
            type: array
            items:
              $ref: "#/definitions/Key"

securityDefinitions:
  api_key:
    type: "apiKey"
    name: "Api-key"
    in: "header"
  key:
    type: "apiKey"
    name: "key"
    in: "query"

definitions:
  CaptureHistory:
    type: "object"
    properties:
      pageCount:
        type: "integer"
        format: "int32"
        description: "Number of pages that can be retrieved"
        example: 7
      pageIndex:
        type: "integer"
        format: "int32"
        description: "Current page number"
        example: 0
      history:
        type: "array"
        items:
          type: "object"
          properties:
            id:
              type: string
              format: uuid
              description: history ID
              example: "204347e0-eaf8-11e9-ac83-338a9cee6792"
            createdAt:
              type: "string"
              example: "2019-10-09T02:43:15.281Z"
            updatedAt:
              type: "string"
              example: "2019-10-09T02:43:15.281Z"
            scheduledCaptureId:
              type: "string"
              format: "uuid"
            status:
              type: string
              enum: [SUCCESS, ERROR, INPROGRESS]
            errorReason:
              type: string
              example: null
            scheduledCapture:
              $ref: "#/definitions/ScheduledCapture"
            fileId:
              type: "string"
              format: "uuid"
              description: ID of the screenshot
              example: "204347e0-eaf8-11e9-ac83-338a9cee6792"
            thumbnailFileId_236:
              type: "string"
              format: "uuid"
              description: ID of the thumbnail
              example: "204347e0-eaf8-11e9-ac83-338a9cee6792"
      details:
        type: object
        properties:
          apps:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                  format: uuid
                  description: App ID
                  example: "204347e0-eaf8-11e9-ac83-338a9cee6792"
                path:
                  type: string
                  description: "Folder and file name used with the App"
                appName:
                  type: string
                appType:
                  type: string
                  enum: [S3, Azure, GDrive, Dropbox, RSS, Slack, FTP, Webhook, SFTP]
                error:
                  type: string
                  description: error message
                success:
                  type: boolean
                imageUrl:
                  type: string
                  description: the URL of the screenshot
                url:
                  type: string
                  description: URL captured
      trackers:
        type: array
        items:
          type: TrackerResult
          example: {"name": "Best Sellers in Waist Trimmers", "shot": "1", "found": 1, "value": "12"}

  ScheduledCapture:
    type: "object"
    required:
    - "id"
    - "name"
    - captureRequest
    - schedule
    - paused
    properties:
      id:
        type: "string"
        format: "uuid"
        example: "204347e0-eaf8-11e9-ac83-338a9cee6792"
      name:
        type: "string"
        example: "My capture"
      paused:
        type: "boolean"
      comment:
        type: "string"
      createdAt:
        type: "string"
        example: "2019-10-09T02:43:15.281Z"
      updatedAt:
        type: "string"
        example: "2019-10-09T02:43:15.281Z"
      captureRequest:
        type: "object"
        required:
          - "browser"
          - "country"
          - "format"
          - "height"
        properties:
          apps:
            type: "array"
            items:
              type: "string"
              format: "uuid"
              description: "App ID"
              example: "204347e0-eaf8-11e9-ac83-338a9cee6792"
          browser:
            type: "string"
            example: "Chrome"
            enum: [Chrome, Firefox, iPhone, "iPhone 12"]
          country:
            type: "string"
            example: "USA"
            enum: [USA, Germany, Italy, Netherlands, UK, Australia]
          cropHeight:
            type: "integer"
            format: "int32"
            example: null
          cropLeft:
            type: "integer"
            format: "int32"
            example: 0
          cropTop:
            type: "integer"
            format: "int32"
            example: 0
          cropBottom:
            type: "integer"
            format: "int32"
            example: null
          emails:
            type: "array"
            items:
              type: "string"
              example: "foo@gmail.com"
          externalMax:
            type: "integer"
            format: "int32"
            example: 0
            description: "Maximum number of external URLs to retrieve from an RSS feed or Sitemap."
          format:
              type: "string"
              enum: [png, jpeg]
              example: png
          height:
            type: "integer"
            format: "int32"
            example: 1024
            description: Browser height
          scrollTo:
            type: "object"
            properties:
              x:
                type: "integer"
                format: "int32"
                example: 0
              y:
                type: "integer"
                format: "int32"
                example: 0
          size:
            type: "string"
            enum: ["Full Page", Screen]
            example: "Full Page"
          steps:
            type: "array"
            items:
              type: "object"
              required:
                - "command"
              properties:
                command:
                  type: "string"
                  enum: [type, click, screenshot, navigate, sleep]
                  example: type
                selector:
                  type: "string"
                  description:  "CSS selector"
                  example: "#login-btn"
                value:
                  type: "string"
                  example: "username"
          tags:
            type: "array"
            items:
              type: "object"
              required:
                - "name"
                - "readOnly"
              properties:
                name:
                  type: "string"
                readOnly:
                  type: "boolean"
                  description: "should always be set to false"
          url:
            type: "string"
            description: "URL to capture when urlType is set to 'single'"
          urlExternal:
            type: "string"
            description: "external feed (RSS, Sitemap) to retrieve when urlType is set to 'external'"
          urlType:
            type: string
            enum: [single, multiple, external]
          urls:
            type: array
            items:
              type: string
              format: uri
              description: "List of URLs to capture when UrlType is set to 'multiple'"
          waitSecond:
            type: integer
            format: "int32"
            example: 5
            description: Number of seconds to wait after the Page Load event
          maxWait:
            type: integer
            format: "int32"
            example: 10
            description: Maximum number of seconds to wait before a page is considered fully loaded.
          hidePopups:
            type: integer
            format: "int32"
            example: 1
            description: Automatically hide popups and overlay on the page (1 = enabled, 0 = disabled).
          dark:
            type: integer
            format: "int32"
            example: 1
            description: Enable dark mode in Chrome and iPhone (1 = enabled, 0 = disabled).
          strictSSL:
            type: integer
            format: "int32"
            example: 1
            description: Enable strict SSL (expired certs, mixed content, etc.).
          width:
            type: integer
            format: "int32"
            example: 1280
            description: Browser width
          zoom:
            type: integer
            format: "int32"
            example: 100
            description: Image zoom - 100 for original size, 200 for 2x the original size, 50 for half the original size, etc.
      schedule:
        type: "object"
        properties:
          daysOfMonth:
            type: array
            items:
              type: integer
              format: int32
              description: Day of the month, from 0 to 30
              example: [0, 10, 20, 30]
          daysofWeek  :
            type: array
            items:
              type: integer
              format: int32
              description: Day of the week from 0 (Sunday) to 6 (Saturday)
              example: [0,1,2,3,4,5,6]
          exactDates:
            type: array
            items:
              type: string
              example: "2020-05-15"
              description: "exact date, year-month-day"
          timesOfDay:
            type: array
            items:
              type: string
              example: "17:05"
              description: "hour:minutes in 24-hour format"
      trackers:
        type: array
        items:
          type: TrackerRequest
          example: {"id": "amazon_category_rank", "input": "B0BFYM54RF"}

  App:
    type: object
    required:
    - id
    - name
    - domain
    - folder
    - file
    properties:
      authentication:
        type: object
        description: "Optional authentication information, used for Google Drive and Dropbox"
      createdAt:
        type: string
        example: "2019-10-09T02:43:15.281Z"
      updatedAt:
        type: string
        example: "2019-10-09T02:43:15.281Z"
      domain:
        type: string
        description: "The domain name or bucket name"
      file:
        type: string
        description: "The file name for the screenshot"
        example: "captures/<domain>.png"
      folder:
        type: string
        description: "The folder where the screenshot should be uploaded"
        example: "<domain>."
      id:
        type: string
        format: uuid
        example: "204347e0-eaf8-11e9-ac83-338a9cee6792"
      name:
        type: string
        example: "My Dropbox"
      type:
        type: string
        enum: [S3, Azure, GDrive, Dropbox, RSS, Slack, FTP, Webhook, SFTP]
      verified:
        type: boolean
        description: whether the App was verified by the user or not

  Key:
    type: "object"
    required:
    - "key"
    properties:
      key:
        type: string
        example: "3LPKyN7XN0QER2ZDGXbo6f0IFjwgMDpOmrzs25K"
      createdAt:
        type: "string"
        example: "2019-10-09T02:43:15.281Z"

  TrackerRequest:
    type: "object"
    required:
    - id
    description: Description of a tracker added to a ScheduledCapture
    properties:
      id:
        type: string
        enum: [amazon_category_rank, amazon_search_rank, google_search_rank, youtube_view, youtube_likes, youtube_comments, twitter_retweets, twitter_likes, twitter_quotetweets]
        description: Predefined tracker
      input:
        type: string
        description: Optional value to track (Amazon product ID, URL, etc.)

  TrackerResult:
    type: "object"
    required:
    - found
    - shot
    description: Description of a tracker returned by a CaptureHistory
    properties:
      found:
        type: integer
        format: int32
        description: 1 if tracker was found, 0 if not found
        example: 1
      shot:
        type: integer
        format: int32
        description: shot number
        example: 1
      error:
        type: string
        description: error message
        example: selector not found
      name:
        type: string
        description: name of the tracker
        example: best toy for kid
      value:
        type: string
        description: value retrieved
        example: 5

externalDocs:
  description: "Blit"
  url: "https://blitapp.com/"