Connections, MCP, And OPENAPI
Purpose and Scope
This page explains the OpenAPI artifact surface that a Turborepo-compatible remote cache server exposes. In this repository, the concrete public behavior is documented as generated API pages for cache artifacts: checking whether an artifact exists, downloading it, uploading it, and querying information about multiple artifacts. A connection, in this context, is the authenticated HTTP boundary between the Turborepo client and a remote cache implementation. If a team places a gateway, catalog, or MCP-style adapter in front of the cache, that layer should preserve the same artifact semantics rather than inventing a different task-cache model.
Sources: apps/docs/content/openapi/artifacts/artifact-exists.mdx, apps/docs/content/openapi/artifacts/artifact-query.mdx, apps/docs/content/openapi/artifacts/download-artifact.mdx, apps/docs/content/openapi/artifacts/upload-artifact.mdx
The artifact API exists because Turborepo’s cache is content-addressed by task hashes. A client can ask whether a server already has the artifact for a hash, reuse the artifact when it is present, or upload the task outputs after a local execution. The documentation snippets make the artifact the shared unit of exchange, not an individual file and not a package. That distinction matters for implementers: the server is storing build result archives keyed by hash, while Turborepo remains responsible for calculating hashes and deciding when task execution is necessary.
Relevant Source Files
- apps/docs/content/openapi/artifacts/artifact-exists.mdx — Generated API page for the
HEAD /artifacts/{hash}operation, including the expected response distinction between an existing and missing artifact. - apps/docs/content/openapi/artifacts/artifact-query.mdx — Generated API page for
POST /artifacts, the optional batch query endpoint that returns metadata for multiple artifact hashes. - apps/docs/content/openapi/artifacts/download-artifact.mdx — Generated API page for
GET /artifacts/{hash}, including the binary download format and content-length verification expectation. - apps/docs/content/openapi/artifacts/upload-artifact.mdx — Generated API page for
PUT /artifacts/{hash}, including the expected upload body format and storage behavior. - apps/docs/content/openapi/artifacts/index.mdx — Artifact section landing page that frames the group as endpoints for uploading, downloading, and querying cache artifacts.
- apps/docs/content/openapi/artifacts/meta.json — Navigation metadata that groups the artifact pages under the Artifacts section.
Core Primitives
The first primitive is the artifact hash. The path-based endpoints use the hash as the stable identifier for a cache artifact, so the same value must refer to the same compressed task output archive across machines. The second primitive is the artifact body, which the documentation describes as a gzip-compressed tarball of cached task outputs. The third primitive is metadata: the batch query endpoint can return information such as size, task duration, and tag, allowing a client to plan cache fetches more efficiently than probing each artifact one at a time.
Sources: apps/docs/content/openapi/artifacts/artifact-query.mdx, apps/docs/content/openapi/artifacts/download-artifact.mdx, apps/docs/content/openapi/artifacts/upload-artifact.mdx
The generated API pages also define a documentation primitive: each page delegates rendering to an API component with the remote-cache document and a single operation tuple. That means the MDX files are not hand-written endpoint implementations; they are reader-facing pages generated from the OpenAPI source of truth. For developers maintaining the docs or building tools around them, the method and path in the operation array are the important bridge between the narrative page and the underlying specification.
System-to-Code Mapping
The artifact section index provides the human overview, while the individual generated pages bind specific HTTP methods to specific paths. Existence checking is a header-only request against the hash path. Downloading and uploading use the same hash path with different methods, so implementations should route by both method and path rather than by path alone. Batch querying uses the collection path, making it the one artifact operation in this page set that is not tied to a single hash in the URL.
Sources: apps/docs/content/openapi/artifacts/index.mdx, apps/docs/content/openapi/artifacts/artifact-exists.mdx, apps/docs/content/openapi/artifacts/download-artifact.mdx, apps/docs/content/openapi/artifacts/upload-artifact.mdx
| Capability | Operation | Source-backed behavior |
|---|---|---|
| Existence check | HEAD /artifacts/{hash} | Returns response headers only; implementers should distinguish present artifacts from absent ones with success or not-found status. |
| Download | GET /artifacts/{hash} | Returns binary artifact data as an octet stream; the artifact is a gzip-compressed tarball of cached outputs. |
| Upload | PUT /artifacts/{hash} | Accepts a gzip-compressed tarball of task outputs and makes it available for later downloads by the same hash. |
| Batch query | POST /artifacts | Optionally returns metadata for multiple artifacts, including fields such as size, task duration, and tag. |
Execution Flow
A typical remote-cache interaction starts with a task hash that Turborepo wants to resolve. The client can check the hash before downloading, or it can request the artifact directly when it expects a hit. If the artifact is available, the server returns the archived task outputs and the client validates the response size against the content-length expectation described by the download page. If the artifact is absent, the client performs the task locally and can then upload the resulting archive for future reuse by other machines.
The batch query endpoint is an optimization rather than the minimum viable cache contract. Its documentation says it is optional for basic cache functionality, but it enables optimized fetching by letting the client ask about several hashes in a single request. That is useful for CI jobs and large workspace runs because a scheduler may know many candidate task hashes before it needs the actual archives. Implementers can support the simpler single-artifact operations first, then add batch metadata when they want to reduce round trips.
Implementation Details and Edge Cases
The HEAD operation is deliberately bodyless. It is equivalent to a GET request where the response contains no body, so servers should avoid returning artifact bytes for this route. The documented behavior is simple: return success when the artifact exists and not-found when it does not. This makes the endpoint safe for lightweight probing and for connection layers that want to decide whether a more expensive download should be attempted. A proxy or adapter should preserve that distinction and should not translate a missing artifact into a generic server failure.
Sources: apps/docs/content/openapi/artifacts/artifact-exists.mdx, apps/docs/content/openapi/artifacts/download-artifact.mdx
Upload and download must agree on archive format. The upload page says the request body should contain a gzip-compressed tarball of task outputs, and the download page says the artifact data is returned in that same compressed archive form. A self-hosted server therefore should store bytes faithfully enough that a later download by hash returns the expected artifact. The download page also calls out content-length verification by the client, which means incorrect headers, truncated streams, or transformed payloads can cause a cache retrieval to fail even when the hash route exists.
Adapter Guidance and Next Steps
When exposing this API through a broader connection system, keep the OpenAPI contract as the compatibility boundary. The adapter may manage credentials, routing, tenancy, or observability, but it should still present the artifact operations with the documented methods, paths, body formats, and status semantics. For readers implementing a remote cache, start with upload, download, and existence checks, then add batch artifact queries for efficiency. For readers operating Turborepo in CI, pair this page with the remote caching and CI guides so the server contract, client authentication, and pipeline behavior are designed together.