Skip to content
Vercel
Remote Cache API

Upload a cache artifact

Uploads a cache artifact identified by the `hash` specified on the path. The cache artifact can then be downloaded with the provided `hash`. The request body should contain a gzip-compressed tarball of the task outputs. The server should store this data and make it available for subsequent downloads.

PUT
/artifacts/{hash}

Authorization

bearerToken
AuthorizationBearer <token>

Bearer token authentication. Pass your authentication token in the Authorization header as Bearer <token>.

For self-hosted implementations, the token format and validation logic is up to the implementer. Common approaches include:

  • Static tokens for simple setups
  • JWT tokens for stateless authentication
  • OAuth2 tokens for integration with identity providers

In: header

Path Parameters

hash*string

The artifact hash. This is a content-addressable hash that uniquely identifies the cached artifact based on task inputs.

Match^[a-fA-F0-9]+$
Length1 <= length

Query Parameters

teamId?string

The team identifier to perform the request on behalf of. Used for multi-tenant cache implementations where artifacts are scoped to teams.

slug?string

The team slug to perform the request on behalf of. Alternative to teamId for identifying the team.

Header Parameters

Content-Length*integer

The artifact size in bytes

Range0 <= value
x-artifact-duration?integer

The time taken to generate the artifact in milliseconds. This value is stored and returned when the artifact is downloaded.

Range0 <= value
x-artifact-tag?string

A base64-encoded tag for this artifact, typically used for verification. This value is stored and returned when the artifact is downloaded via the x-artifact-tag response header.

Lengthlength <= 600
x-artifact-sha?string

The git SHA of the HEAD commit at the time this artifact was produced. This value is stored and returned when the artifact is downloaded or checked via the x-artifact-sha response header.

x-artifact-dirty-hash?string

A hash summarizing all uncommitted changes (staged, unstaged, and untracked files) in the working tree when this artifact was produced. This value is stored and returned when the artifact is downloaded or checked via the x-artifact-dirty-hash response header.

x-artifact-client-ci?string

The continuous integration or delivery environment where this artifact operation is being performed. Examples: github-actions, circleci, jenkins.

Lengthlength <= 50
x-artifact-client-interactive?integer

Indicates whether the client is running in an interactive shell. 1 for interactive, 0 for non-interactive (CI/scripts).

Value in0 | 1

Request Body

application/octet-stream

The artifact data as a gzip-compressed tarball

body*unknown

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://localhost:3000/artifacts/string" \  -H "Content-Length: 0"
{
  "urls": [
    "http://example.com"
  ]
}
{
  "urls": [
    "http://example.com"
  ]
}
{
  "code": "string",
  "message": "string"
}
{
  "code": "string",
  "message": "string"
}
{
  "code": "string",
  "message": "string"
}