artifacts

Reference

4 min read

Artifacts

Check if a cache artifact exists

head/v8/artifacts/{hash}

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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/12HKQaOmR5t5Uy6vdcQsNIiZgHGB?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "head"
6})

Parameters

Path Params

Query Params

Path Parameter	Description
hash	string required The artifact hash Example:`12HKQaOmR5t5Uy6vdcQsNIiZgHGB`

Response

The artifact was found and headers are returned

Response Codes

Code	Description
`200`	The artifact was found and headers are returned
`400`	One of the provided values in the request query is invalid.
`401`
`402`	The account was soft-blocked for an unhandled reason. The account is missing a payment so payment method must be updated
`403`	You do not have permission to access this resource. The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings. The Remote Caching usage limit has been reached for this account for this billing cycle. Remote Caching has been disabled for this team or user. An owner can enable it in the billing settings.
`404`	The artifact was not found

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/12HKQaOmR5t5Uy6vdcQsNIiZgHGB?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "head"
6})

Query information about an artifact

post/v8/artifacts

Query information about an array of artifacts.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "hashes": "SOME_ARRAY OF STRING_VALUE"
4  },
5  "headers": {
6    "Authorization": "Bearer <TOKEN>"
7  },
8  "method": "post"
9})

Parameters

Query Params

Body Params

Query Parameter	Description
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.

Response Codes

Code	Description
`200`
`400`	One of the provided values in the request body is invalid.
`401`
`402`	The account was soft-blocked for an unhandled reason. The account is missing a payment so payment method must be updated
`403`	You do not have permission to access this resource. The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings. The Remote Caching usage limit has been reached for this account for this billing cycle. Remote Caching has been disabled for this team or user. An owner can enable it in the billing settings.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "hashes": "SOME_ARRAY OF STRING_VALUE"
4  },
5  "headers": {
6    "Authorization": "Bearer <TOKEN>"
7  },
8  "method": "post"
9})

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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/12HKQaOmR5t5Uy6vdcQsNIiZgHGB?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>",
4    "x-artifact-client-ci": "VERCEL",
5    "x-artifact-client-interactive": 0
6  },
7  "method": "get"
8})

Parameters

Path Params

Query Params

Header Params

Path Parameter	Description
hash	string required The artifact hash Example:`12HKQaOmR5t5Uy6vdcQsNIiZgHGB`

Response

An octet stream response that will be piped to the response stream.

string (binary)
An octet stream response that will be piped to the response stream.

Response Codes

Code	Description
`200`	The artifact was found and is downloaded as a stream. Content-Length should be verified.
`400`	One of the provided values in the request query is invalid. One of the provided values in the headers is invalid
`401`
`402`	The account was soft-blocked for an unhandled reason. The account is missing a payment so payment method must be updated
`403`	You do not have permission to access this resource. The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings. The Remote Caching usage limit has been reached for this account for this billing cycle. Remote Caching has been disabled for this team or user. An owner can enable it in the billing settings.
`404`	The artifact was not found

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/12HKQaOmR5t5Uy6vdcQsNIiZgHGB?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>",
4    "x-artifact-client-ci": "VERCEL",
5    "x-artifact-client-interactive": 0
6  },
7  "method": "get"
8})

Record an artifacts cache usage event

post/v8/artifacts/events

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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/events?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "event": "HIT",
4    "hash": "12HKQaOmR5t5Uy6vdcQsNIiZgHGB",
5    "sessionId": "SOME_STRING_VALUE",
6    "source": "LOCAL",
7    "duration": 400
8  },
9  "headers": {
10    "Authorization": "Bearer <TOKEN>",
11    "x-artifact-client-ci": "VERCEL",
12    "x-artifact-client-interactive": 0
13  },
14  "method": "post"
15})

Parameters

Query Params

Body Params

Header Params

Query Parameter	Description
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.

Response

Success. Event recorded.

Response Codes

Code	Description
`200`	Success. Event recorded.
`400`	One of the provided values in the request body is invalid. One of the provided values in the headers is invalid
`401`
`402`	The account was soft-blocked for an unhandled reason. The account is missing a payment so payment method must be updated
`403`	You do not have permission to access this resource. The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings. The Remote Caching usage limit has been reached for this account for this billing cycle. Remote Caching has been disabled for this team or user. An owner can enable it in the billing settings.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/events?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "body": {
3    "event": "HIT",
4    "hash": "12HKQaOmR5t5Uy6vdcQsNIiZgHGB",
5    "sessionId": "SOME_STRING_VALUE",
6    "source": "LOCAL",
7    "duration": 400
8  },
9  "headers": {
10    "Authorization": "Bearer <TOKEN>",
11    "x-artifact-client-ci": "VERCEL",
12    "x-artifact-client-interactive": 0
13  },
14  "method": "post"
15})

Get status of Remote Caching for this principal

get/v8/artifacts/status

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.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/status?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Parameters

Query Params

Query Parameter	Description
slug	string The Team slug to perform the request on behalf of.
teamId	string The Team identifier to perform the request on behalf of.

Response

statusstringRequired
One of: disabled | enabled | over_limit | paused

Response Codes

Code	Description
`200`
`400`
`401`
`402`	The account was soft-blocked for an unhandled reason. The account is missing a payment so payment method must be updated
`403`	You do not have permission to access this resource.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/status?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>"
4  },
5  "method": "get"
6})

Upload a cache artifact

put/v8/artifacts/{hash}

Uploads a cache artifact identified by the hash specified on the path. The cache artifact can then be downloaded with the provided hash.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/12HKQaOmR5t5Uy6vdcQsNIiZgHGB?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>",
4    "Content-Length": "SOME_NUMBER_VALUE",
5    "x-artifact-client-ci": "VERCEL",
6    "x-artifact-client-interactive": 0,
7    "x-artifact-duration": 400,
8    "x-artifact-tag": "Tc0BmHvJYMIYJ62/zx87YqO0Flxk+5Ovip25NY825CQ="
9  },
10  "method": "put"
11})

Parameters

Path Params

Query Params

Header Params

Path Parameter	Description
hash	string required The artifact hash Example:`12HKQaOmR5t5Uy6vdcQsNIiZgHGB`

Response

urlsarrayRequired
Array of URLs where the artifact was updated
Example: ["https://api.vercel.com/v2/now/artifact/12HKQaOmR5t5Uy6vdcQsNIiZgHGB"]

Response Codes

Code	Description
`202`	File successfully uploaded
`400`	One of the provided values in the request query is invalid. One of the provided values in the headers is invalid File size is not valid
`401`
`402`	The account was soft-blocked for an unhandled reason. The account is missing a payment so payment method must be updated
`403`	You do not have permission to access this resource. The customer has reached their spend cap limit and has been paused. An owner can disable the cap or raise the limit in settings. The Remote Caching usage limit has been reached for this account for this billing cycle. Remote Caching has been disabled for this team or user. An owner can enable it in the billing settings.

Optional params

fetch-request

1await fetch("https://api.vercel.com/v8/artifacts/12HKQaOmR5t5Uy6vdcQsNIiZgHGB?slug=SOME_STRING_VALUE&teamId=SOME_STRING_VALUE", {
2  "headers": {
3    "Authorization": "Bearer <TOKEN>",
4    "Content-Length": "SOME_NUMBER_VALUE",
5    "x-artifact-client-ci": "VERCEL",
6    "x-artifact-client-interactive": 0,
7    "x-artifact-duration": 400,
8    "x-artifact-tag": "Tc0BmHvJYMIYJ62/zx87YqO0Flxk+5Ovip25NY825CQ="
9  },
10  "method": "put"
11})

Last updated on April 27, 2024

List Deployment Aliases

Check if a cache artifact exists

Was this helpful?