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

AuthorizationBearer token · headerrequired

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

Path parameters

hashstringrequired

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

min length 1 · matches ^[a-fA-F0-9]+$

Query parameters

teamIdstring

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

slugstring

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

Header parameters

Content-Lengthintegerrequired

The artifact size in bytes

min 0

x-artifact-durationinteger

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

min 0

x-artifact-tagstring

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.

max length 600

x-artifact-shastring

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-hashstring

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-cistring

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

max length 50

x-artifact-client-interactiveinteger

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

Allowed:01

Request body

requiredapplication/octet-stream

The artifact data as a gzip-compressed tarball

any

Responses

200

Artifact uploaded successfully (alternative success response)

urlsstring<uri>[]required

Array of URLs where the artifact was stored. Implementers can return the storage location(s) for debugging purposes.

202

Artifact accepted for storage

urlsstring<uri>[]required

Array of URLs where the artifact was stored. Implementers can return the storage location(s) for debugging purposes.

400

Bad request. One or more of the provided values in the request query, headers, or body is invalid.

codestringrequired

A machine-readable error code

messagestringrequired

A human-readable error message

401

Unauthorized. The request is missing a valid authentication token or the token is invalid.

codestringrequired

A machine-readable error code

messagestringrequired

A human-readable error message

403

Forbidden. The authenticated user does not have permission to access this resource.

codestringrequired

A machine-readable error code

messagestringrequired

A human-readable error message

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

hashpath*The artifact hash. This is a content-addressable hash that uniquely identifies the cached artifact based on task inputs.teamIdqueryThe team identifier to perform the request on behalf of. Used for multi-tenant cache implementations where artifacts are scoped to teams.slugqueryThe team slug to perform the request on behalf of. Alternative to `teamId` for identifying the team.Content-Lengthheader*The artifact size in bytesx-artifact-durationheaderThe time taken to generate the artifact in milliseconds. This value is stored and returned when the artifact is downloaded.x-artifact-tagheaderA 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.x-artifact-shaheaderThe 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-hashheaderA 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-ciheaderThe continuous integration or delivery environment where this artifact operation is being performed. Examples: `github-actions`, `circleci`, `jenkins`.x-artifact-client-interactiveheaderIndicates whether the client is running in an interactive shell. `1` for interactive, `0` for non-interactive (CI/scripts).

Bodyapplication/octet-stream

Request body

Request

curl -X PUT 'https://turborepo-remote-cache.example.workers.dev/v8/artifacts/string' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Length: 0' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/octet-stream' \
  -d 'null'

const response = await fetch("https://turborepo-remote-cache.example.workers.dev/v8/artifacts/string", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Length": "0",
    "Accept": "application/json",
    "Content-Type": "application/octet-stream"
  },
  body: "null"
});

import requests

response = requests.put(
    "https://turborepo-remote-cache.example.workers.dev/v8/artifacts/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Length": "0",
        "Accept": "application/json",
        "Content-Type": "application/octet-stream"
    },
    data="null",
)

Response

{
  "urls": [
    "http://example.com"
  ]
}

{
  "urls": [
    "http://example.com"
  ]
}

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}

{
  "code": "string",
  "message": "string"
}