---
title: "Runner-owned Actions cache control plane"
method: POST
path: "/api/v1/github_runner_cache"
tags: ["github_runner_cache"]
---

# Runner-owned Actions cache control plane

`POST /api/v1/github_runner_cache`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/github_runner_cache`
- Auth: HTTP bearer

Internal runner protocol. Requires an expiring invocation-attempt bearer credential; user API tokens do not authorize this endpoint. Repository and branch scope come from the runner's actual GitHub assignment. Archive bytes flow through the runner's CloudBucketMount, not this API.

## Request body

- object
  - `operation` 'GetCacheEntryDownloadURL' | 'CreateCacheEntry' | 'ReserveUpload' | 'FinalizeCacheEntryUpload', required
  - `key` string
  - `version` string
  - `restore_keys` string[]
  - `entry_id` string
  - `size_bytes` string

## Response `200`

Cache lookup, upload reservation, or publication result

- object
  - `ok` boolean, required
  - `entry_id` string
  - `upload_path` string
  - `signed_download_url` string
  - `matched_key` string
  - `size_bytes` string

## Other responses

- `401`: Invalid or expired runner attempt
- `403`: Forbidden
- `404`: Not found
- `409`: Cache key exists or upload belongs to another attempt
- `422`: Unprocessable entity
- `502`: Bad gateway
- `503`: Namespace disabled or actual assignment not yet observed
- `507`: Namespace capacity exhausted

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/74298a24e040?raw)