openapi: 3.0.0
servers:
  - url: https://api.archive.org
info:
  contact:
    x-twitter: internetarchive
  description: API for Internet Archive's Wayback Machine
  title: Wayback API
  version: 1.0.0
  x-apisguru-categories:
    - search
  x-logo:
    url: https://twitter.com/internetarchive/profile_image?size=original
  x-origin:
    - format: openapi
      url: https://raw.githubusercontent.com/ArchiveLabs/api.archive.org/master/swagger/wayback.json
      version: "3.0"
  x-providerName: archive.org
  x-serviceName: wayback
paths:
  /wayback/v1/available:
    get:
      parameters:
        - $ref: "#/components/parameters/url"
        - $ref: "#/components/parameters/timestamp"
        - $ref: "#/components/parameters/callback"
        - $ref: "#/components/parameters/timeout"
        - $ref: "#/components/parameters/closest"
        - $ref: "#/components/parameters/status_code"
        - $ref: "#/components/parameters/tag"
      responses:
        "200":
          $ref: "#/components/responses/AvailabilityResults"
        default:
          content:
            application/javascript:
              schema:
                $ref: "#/components/schemas/Error"
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Unexpected error
    post:
      parameters:
        - $ref: "#/components/parameters/url"
        - $ref: "#/components/parameters/timestamp"
        - $ref: "#/components/parameters/callback"
        - $ref: "#/components/parameters/timeout"
        - $ref: "#/components/parameters/closest"
        - $ref: "#/components/parameters/status_code"
        - $ref: "#/components/parameters/tag"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AvailabilityRequests"
          application/x-www-form-urlencoded:
            schema:
              $ref: "#/components/schemas/AvailabilityRequests"
          text/csv:
            schema:
              $ref: "#/components/schemas/AvailabilityRequests"
      responses:
        "200":
          $ref: "#/components/responses/AvailabilityResults"
        default:
          content:
            application/javascript:
              schema:
                $ref: "#/components/schemas/Error"
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
          description: Unexpected error
components:
  parameters:
    callback:
      description: |
        Specifies a JavaScript function func, for a JSON-P response. When provided, results are wrapped as `callback(data)`, and the returned MIME type is application/javascript. This causes the caller to automatically run the func with the JSON results as its argument.
      in: query
      name: callback
      required: false
      schema:
        type: string
    closest:
      description: |
        The direction specifies whether to match archived timestamps that are before the provided one, after, or the default either (closest in either direction). Must be before, after, or either. May be overidden by individual requests.
      in: query
      name: closest
      required: false
      schema:
        default: either
        enum:
          - either
          - before
          - after
        type: string
    status_code:
      description: |
        HTTP status codes to filter by. Only results with these codes will be returned
      explode: true
      in: query
      name: status_code
      required: false
      schema:
        enum:
          - 200
          - 201
          - 202
          - 203
          - 204
          - 205
          - 206
          - 300
          - 301
          - 302
          - 303
          - 304
          - 305
          - 306
          - 307
          - 308
          - 400
          - 401
          - 402
          - 403
          - 404
          - 405
          - 406
          - 407
          - 408
          - 409
          - 410
          - 411
          - 412
          - 413
          - 414
          - 415
          - 416
          - 417
          - 418
          - 421
          - 426
          - 428
          - 429
          - 431
          - 500
          - 501
          - 502
          - 503
          - 504
          - 505
          - 506
          - 507
          - 511
        type: integer
    tag:
      description: |
        The optional tag can have any value, and is returned with the results; it can be used to help collate input and output values.
      in: query
      name: tag
      required: false
      schema:
        type: string
    timeout:
      description: |
        Timeout is the maximum number of seconds to wait for the availability API to get its underlying results from the CDX server. The default value is 5.0.
      in: query
      name: timeout
      required: false
      schema:
        default: 5
        type: number
    timestamp:
      description: |
        Timestamp requested in ISO 8601 format. The following formats are acceptable:
         - YYYY
         - YYYY-MM
         - YYYY-MM-DD
         - YYYY-MM-DDTHH:mm:SSz
         - YYYY-MM-DD:HH:mm+00:00
      in: query
      name: timestamp
      required: false
      schema:
        type: string
    url:
      description: A single URL to query.
      in: query
      name: url
      required: true
      schema:
        type: string
  responses:
    AvailabilityResults:
      content:
        applcation/json:
          examples:
            response:
              value:
                results:
                  - snapshot:
                      status: "200"
                      timestamp: 2016-04-07T19:39:18Z
                      url: http://web.archive.org/web/20160111075133/http://entish.org/
                    tag: "0"
                    timestamp: 2016-04-07T19:39:18Z
                    url: http://www.entish.org
                  - snapshot:
                      timestamp: 2016-04-13T13:20:39Z
                      url: http://web.archive.org/web/20160413132039/http://www.cnn.com/
                    tag: "1"
                    url: http://www.cnn.com/
                  - snapshot: {}
                    tag: "2"
                    timestamp: 2016-04-07T19:39:18Z
                    url: http://www.youcantfindthis.cat
        application/javascript:
          schema:
            $ref: "#/components/schemas/AvailabilityResults"
        application/json:
          schema:
            $ref: "#/components/schemas/AvailabilityResults"
      description: Nominal Availability results
  schemas:
    ArchivedResult:
      properties:
        snapshot:
          $ref: "#/components/schemas/Snapshot"
        tag:
          description: The user-supplied tag for use in collation
          type: string
        timestamp:
          description: The _intepreted_ timestamp requested, in [RFC 3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html) format
          format: dateTime
          type: string
        url:
          description: The URL requested
          type: string
      required:
        - url
        - timestamp
        - snapshot
      type: object
    AvailabilityRequest:
      properties:
        closest:
          description: The direction to find the closest snapshot to the requested timestamp
          enum:
            - either
            - after
            - before
          type: string
        tag:
          description: A user-supplied tag, used for collation
          type: string
        timestamp:
          description: |
            Timestamp requested in ISO 8601 format. The following formats are acceptable: - YYYY - YYYY-MM - YYYY-MM-DD - YYYY-MM-DDTHH:mm:SSz - YYYY-MM-DD:HH:mm+00:00
          type: string
        url:
          description: The URL requested
          type: string
      required:
        - url
      type: object
    AvailabilityRequests:
      example:
        - tag: "0"
          timestamp: 2016-04-07T19:39:18Z
          url: http://www.entish.org
        - tag: "1"
          url: http://www.cnn.com/
        - tag: "2"
          timestamp: 2016-04-07T19:39:18Z
          url: http://www.youcantfindthis.cat
      items:
        $ref: "#/components/schemas/AvailabilityRequest"
      type: array
    AvailabilityResults:
      properties:
        results:
          description: A list of results
          items:
            $ref: "#/components/schemas/ArchivedResult"
          type: array
      required:
        - results
      type: object
    Error:
      properties:
        code:
          format: integer
          type: integer
        message:
          type: string
      type: object
    Snapshot:
      properties:
        status:
          description: The HTTP status of the URL requested
          type: integer
        timestamp:
          description: The timestamp of the snapshot in [RFC 3339](http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html) format
          format: dateTime
          type: string
        url:
          description: The URL requested
          type: string
      type: object
