vercel-openapi.json

{
  "openapi": "3.0.3",
  "info": {
    "title": "Turborepo Remote Cache API",
    "description": "Turborepo is an intelligent build system optimized for JavaScript and TypeScript codebases.",
    "version": "8.0.0"
  },
  "servers": [
    {
      "url": "https://api.vercel.com",
      "description": "Production API"
    }
  ],
  "paths": {
    "/v8/artifacts/events": {
      "post": {
        "description": "Records an artifacts cache usage event. The body of this request is an array of cache usage events. The supported event types are `HIT` and `MISS`. The source is either `LOCAL` the cache event was on the users filesystem cache or `REMOTE` if the cache event is for a remote cache. When the event is a `HIT` the request also accepts a number `duration` which is the time taken to generate the artifact in the cache.",
        "operationId": "recordEvents",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "summary": "Record an artifacts cache usage event",
        "tags": [
          "artifacts"
        ],
        "responses": {
          "200": {
            "description": "Success. Event recorded."
          },
          "400": {
            "description": "One of the provided values in the request body is invalid.\nOne of the provided values in the headers is invalid"
          },
          "401": {
            "description": ""
          },
          "402": {
            "description": "The account was soft-blocked for an unhandled reason.\nThe account is missing a payment so payment method must be updated"
          },
          "403": {
            "description": "The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings.\nThe Remote Caching usage limit has been reached for this account for this billing cycle.\nRemote Caching has been disabled for this team or user. An owner can enable it in the billing settings.\nYou do not have permission to access this resource."
          }
        },
        "parameters": [
          {
            "in": "header",
            "description": "The continuous integration or delivery environment where this artifact is downloaded.",
            "schema": {
              "type": "string",
              "description": "The continuous integration or delivery environment where this artifact is downloaded.",
              "example": "VERCEL",
              "maxLength": 50
            },
            "name": "x-artifact-client-ci"
          },
          {
            "in": "header",
            "description": "1 if the client is an interactive shell. Otherwise 0",
            "schema": {
              "type": "integer",
              "description": "1 if the client is an interactive shell. Otherwise 0",
              "example": 0,
              "minimum": 0,
              "maximum": 1
            },
            "name": "x-artifact-client-interactive"
          },
          {
            "description": "The Team identifier to perform the request on behalf of.",
            "in": "query",
            "name": "teamId",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The Team slug to perform the request on behalf of.",
            "in": "query",
            "name": "slug",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "sessionId",
                    "source",
                    "hash",
                    "event"
                  ],
                  "properties": {
                    "sessionId": {
                      "type": "string",
                      "description": "A UUID (universally unique identifer) for the session that generated this event."
                    },
                    "source": {
                      "type": "string",
                      "enum": [
                        "LOCAL",
                        "REMOTE"
                      ],
                      "description": "One of `LOCAL` or `REMOTE`. `LOCAL` specifies that the cache event was from the user's filesystem cache. `REMOTE` specifies that the cache event is from a remote cache."
                    },
                    "event": {
                      "type": "string",
                      "enum": [
                        "HIT",
                        "MISS"
                      ],
                      "description": "One of `HIT` or `MISS`. `HIT` specifies that a cached artifact for `hash` was found in the cache. `MISS` specifies that a cached artifact with `hash` was not found."
                    },
                    "hash": {
                      "type": "string",
                      "example": "12HKQaOmR5t5Uy6vdcQsNIiZgHGB",
                      "description": "The artifact hash"
                    },
                    "duration": {
                      "type": "number",
                      "description": "The time taken to generate the artifact. This should be sent as a body parameter on `HIT` events.",
                      "example": 400
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v8/artifacts/status": {
      "get": {
        "description": "Check the status of Remote Caching for this principal. Returns a JSON-encoded status indicating if Remote Caching is enabled, disabled, or disabled due to usage limits.",
        "operationId": "status",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "summary": "Get status of Remote Caching for this principal",
        "tags": [
          "artifacts"
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "disabled",
                        "enabled",
                        "over_limit",
                        "paused"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ],
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": ""
          },
          "401": {
            "description": ""
          },
          "402": {
            "description": "The account was soft-blocked for an unhandled reason.\nThe account is missing a payment so payment method must be updated"
          },
          "403": {
            "description": "You do not have permission to access this resource."
          }
        },
        "parameters": [
          {
            "description": "The Team identifier to perform the request on behalf of.",
            "in": "query",
            "name": "teamId",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The Team slug to perform the request on behalf of.",
            "in": "query",
            "name": "slug",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v8/artifacts/{hash}": {
      "put": {
        "description": "Uploads a cache artifact identified by the `hash` specified on the path. The cache artifact can then be downloaded with the provided `hash`.",
        "operationId": "uploadArtifact",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "summary": "Upload a cache artifact",
        "tags": [
          "artifacts"
        ],
        "responses": {
          "202": {
            "description": "File successfully uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "urls": {
                      "items": {
                        "type": "string"
                      },
                      "type": "array",
                      "description": "Array of URLs where the artifact was updated",
                      "example": [
                        "https://api.vercel.com/v2/now/artifact/12HKQaOmR5t5Uy6vdcQsNIiZgHGB"
                      ]
                    }
                  },
                  "required": [
                    "urls"
                  ],
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "One of the provided values in the request query is invalid.\nOne of the provided values in the headers is invalid\nFile size is not valid"
          },
          "401": {
            "description": ""
          },
          "402": {
            "description": "The account was soft-blocked for an unhandled reason.\nThe account is missing a payment so payment method must be updated"
          },
          "403": {
            "description": "The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings.\nThe Remote Caching usage limit has been reached for this account for this billing cycle.\nRemote Caching has been disabled for this team or user. An owner can enable it in the billing settings.\nYou do not have permission to access this resource."
          }
        },
        "parameters": [
          {
            "in": "header",
            "description": "The artifact size in bytes",
            "required": true,
            "schema": {
              "description": "The artifact size in bytes",
              "type": "number"
            },
            "name": "Content-Length"
          },
          {
            "in": "header",
            "description": "The time taken to generate the uploaded artifact in milliseconds.",
            "required": false,
            "schema": {
              "type": "number",
              "description": "The time taken to generate the uploaded artifact in milliseconds.",
              "example": 400
            },
            "name": "x-artifact-duration"
          },
          {
            "in": "header",
            "description": "The continuous integration or delivery environment where this artifact was generated.",
            "required": false,
            "schema": {
              "type": "string",
              "description": "The continuous integration or delivery environment where this artifact was generated.",
              "example": "VERCEL",
              "maxLength": 50
            },
            "name": "x-artifact-client-ci"
          },
          {
            "in": "header",
            "description": "1 if the client is an interactive shell. Otherwise 0",
            "required": false,
            "schema": {
              "type": "integer",
              "description": "1 if the client is an interactive shell. Otherwise 0",
              "example": 0,
              "minimum": 0,
              "maximum": 1
            },
            "name": "x-artifact-client-interactive"
          },
          {
            "in": "header",
            "description": "The base64 encoded tag for this artifact. The value is sent back to clients when the artifact is downloaded as the header `x-artifact-tag`",
            "required": false,
            "schema": {
              "type": "string",
              "description": "The base64 encoded tag for this artifact. The value is sent back to clients when the artifact is downloaded as the header `x-artifact-tag`",
              "example": "Tc0BmHvJYMIYJ62/zx87YqO0Flxk+5Ovip25NY825CQ=",
              "maxLength": 600
            },
            "name": "x-artifact-tag"
          },
          {
            "name": "hash",
            "description": "The artifact hash",
            "in": "path",
            "required": true,
            "schema": {
              "example": "12HKQaOmR5t5Uy6vdcQsNIiZgHGB",
              "description": "The artifact hash",
              "type": "string"
            }
          },
          {
            "description": "The Team identifier to perform the request on behalf of.",
            "in": "query",
            "name": "teamId",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The Team slug to perform the request on behalf of.",
            "in": "query",
            "name": "slug",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        }
      },
      "get": {
        "description": "Downloads a cache artifact indentified by its `hash` specified on the request path. The artifact is downloaded as an octet-stream. The client should verify the content-length header and response body.",
        "operationId": "downloadArtifact",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "summary": "Download a cache artifact",
        "tags": [
          "artifacts"
        ],
        "responses": {
          "200": {
            "description": "The artifact was found and is downloaded as a stream. Content-Length should be verified.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string",
                  "format": "binary",
                  "description": "An octet stream response that will be piped to the response stream."
                }
              }
            }
          },
          "400": {
            "description": "One of the provided values in the request query is invalid.\nOne of the provided values in the headers is invalid"
          },
          "401": {
            "description": ""
          },
          "402": {
            "description": "The account was soft-blocked for an unhandled reason.\nThe account is missing a payment so payment method must be updated"
          },
          "403": {
            "description": "The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings.\nThe Remote Caching usage limit has been reached for this account for this billing cycle.\nRemote Caching has been disabled for this team or user. An owner can enable it in the billing settings.\nYou do not have permission to access this resource."
          },
          "404": {
            "description": "The artifact was not found"
          }
        },
        "parameters": [
          {
            "in": "header",
            "description": "The continuous integration or delivery environment where this artifact is downloaded.",
            "schema": {
              "type": "string",
              "description": "The continuous integration or delivery environment where this artifact is downloaded.",
              "example": "VERCEL",
              "maxLength": 50
            },
            "name": "x-artifact-client-ci"
          },
          {
            "in": "header",
            "description": "1 if the client is an interactive shell. Otherwise 0",
            "schema": {
              "type": "integer",
              "description": "1 if the client is an interactive shell. Otherwise 0",
              "example": 0,
              "minimum": 0,
              "maximum": 1
            },
            "name": "x-artifact-client-interactive"
          },
          {
            "name": "hash",
            "description": "The artifact hash",
            "in": "path",
            "required": true,
            "schema": {
              "example": "12HKQaOmR5t5Uy6vdcQsNIiZgHGB",
              "description": "The artifact hash",
              "type": "string"
            }
          },
          {
            "description": "The Team identifier to perform the request on behalf of.",
            "in": "query",
            "name": "teamId",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The Team slug to perform the request on behalf of.",
            "in": "query",
            "name": "slug",
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "head": {
        "description": "Check that a cache artifact with the given `hash` exists. This request returns response headers only and is equivalent to a `GET` request to this endpoint where the response contains no body.",
        "operationId": "artifactExists",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "summary": "Check if a cache artifact exists",
        "tags": [
          "artifacts"
        ],
        "responses": {
          "200": {
            "description": "The artifact was found and headers are returned"
          },
          "400": {
            "description": "One of the provided values in the request query is invalid."
          },
          "401": {
            "description": ""
          },
          "402": {
            "description": "The account was soft-blocked for an unhandled reason.\nThe account is missing a payment so payment method must be updated"
          },
          "403": {
            "description": "The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings.\nThe Remote Caching usage limit has been reached for this account for this billing cycle.\nRemote Caching has been disabled for this team or user. An owner can enable it in the billing settings.\nYou do not have permission to access this resource."
          },
          "404": {
            "description": "The artifact was not found"
          }
        },
        "parameters": [
          {
            "name": "hash",
            "description": "The artifact hash",
            "in": "path",
            "required": true,
            "schema": {
              "example": "12HKQaOmR5t5Uy6vdcQsNIiZgHGB",
              "description": "The artifact hash",
              "type": "string"
            }
          },
          {
            "description": "The Team identifier to perform the request on behalf of.",
            "in": "query",
            "name": "teamId",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The Team slug to perform the request on behalf of.",
            "in": "query",
            "name": "slug",
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/v8/artifacts": {
      "post": {
        "description": "Query information about an array of artifacts.",
        "operationId": "artifactQuery",
        "security": [
          {
            "bearerToken": []
          }
        ],
        "summary": "Query information about an artifact",
        "tags": [
          "artifacts"
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "nullable": true,
                    "oneOf": [
                      {
                        "properties": {
                          "size": {
                            "type": "number"
                          },
                          "taskDurationMs": {
                            "type": "number"
                          },
                          "tag": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "size",
                          "taskDurationMs"
                        ],
                        "type": "object"
                      },
                      {
                        "properties": {
                          "error": {
                            "properties": {
                              "message": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "message"
                            ],
                            "type": "object"
                          }
                        },
                        "required": [
                          "error"
                        ],
                        "type": "object"
                      }
                    ]
                  },
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "One of the provided values in the request body is invalid."
          },
          "401": {
            "description": ""
          },
          "402": {
            "description": "The account was soft-blocked for an unhandled reason.\nThe account is missing a payment so payment method must be updated"
          },
          "403": {
            "description": "The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings.\nThe Remote Caching usage limit has been reached for this account for this billing cycle.\nRemote Caching has been disabled for this team or user. An owner can enable it in the billing settings.\nYou do not have permission to access this resource."
          }
        },
        "parameters": [
          {
            "description": "The Team identifier to perform the request on behalf of.",
            "in": "query",
            "name": "teamId",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The Team slug to perform the request on behalf of.",
            "in": "query",
            "name": "slug",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "hashes"
                ],
                "properties": {
                  "hashes": {
                    "items": {
                      "type": "string"
                    },
                    "description": "artifact hashes",
                    "type": "array"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerToken": {
        "type": "http",
        "description": "Default authentication mechanism",
        "scheme": "bearer"
      }
    }
  }
}