openapi: 3.0.3
info:
  title: Turborepo Remote Cache analytics artifacts API
  description: 'The Turborepo Remote Cache API specification defines the HTTP interface that any remote cache server must implement to be compatible with Turborepo. This spec enables self-hosted remote caching, allowing teams to run their own cache servers.


    The remote cache stores build artifacts (outputs from tasks like `build`, `lint`, `test`) identified by content-addressable hashes. When Turborepo encounters a task that matches a previously cached result, it can download the artifact instead of re-executing the task.'
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    name: Turborepo
    url: https://turbo.build
servers:
- url: '{protocol}://{host}'
  description: Self-hosted Remote Cache Server
  variables:
    protocol:
      default: https
      enum:
      - http
      - https
      description: Protocol to use for the remote cache server
    host:
      default: localhost:3000
      description: Hostname and port of the remote cache server
- url: https://api.vercel.com
  description: 'Vercel Remote Cache (reference implementation) (spec: https://openapi.vercel.com)'
tags:
- name: artifacts
  description: Operations for managing cache artifacts
paths:
  /artifacts/status:
    get:
      operationId: getArtifactStatus
      summary: Get remote caching status
      description: 'Check the status of Remote Caching for the authenticated user or team. Returns a JSON-encoded status indicating if Remote Caching is enabled, disabled, or disabled due to usage limits.


        Implementers should return `enabled` if the authenticated principal is allowed to use the cache, or `disabled` if not. The `over_limit` and `paused` statuses are optional and can be used to indicate usage limits or temporary suspension.'
      tags:
      - artifacts
      security:
      - bearerToken: []
      parameters:
      - $ref: '#/components/parameters/TeamId'
      - $ref: '#/components/parameters/Slug'
      responses:
        '200':
          description: Remote caching status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CachingStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /artifacts/{hash}:
    parameters:
    - $ref: '#/components/parameters/ArtifactHash'
    - $ref: '#/components/parameters/TeamId'
    - $ref: '#/components/parameters/Slug'
    head:
      operationId: artifactExists
      summary: Check if artifact exists
      description: '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.


        Implementers should return 200 if the artifact exists, or 404 if it does not.'
      tags:
      - artifacts
      security:
      - bearerToken: []
      responses:
        '200':
          description: Artifact exists
          headers:
            Content-Length:
              description: The size of the artifact in bytes
              schema:
                type: integer
            x-artifact-duration:
              description: The time taken to generate the artifact in milliseconds (if stored)
              schema:
                type: integer
            x-artifact-sha:
              description: The git SHA of the commit that produced this artifact (if stored)
              schema:
                type: string
            x-artifact-dirty-hash:
              description: A hash summarizing uncommitted changes in the working tree when this artifact was produced (if stored)
              schema:
                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ArtifactNotFound'
    get:
      operationId: downloadArtifact
      summary: Download a cache artifact
      description: 'Downloads a cache artifact identified by its `hash` specified on the request path. The artifact is downloaded as an octet-stream (binary data).


        The artifact data is a gzip-compressed tarball containing the cached task outputs. The client will verify the content-length header against the response body size.'
      tags:
      - artifacts
      security:
      - bearerToken: []
      parameters:
      - $ref: '#/components/parameters/ArtifactClientCI'
      - $ref: '#/components/parameters/ArtifactClientInteractive'
      responses:
        '200':
          description: Artifact downloaded successfully
          headers:
            Content-Length:
              description: The size of the artifact in bytes
              schema:
                type: integer
            x-artifact-duration:
              description: The time taken to generate the artifact in milliseconds
              schema:
                type: integer
            x-artifact-tag:
              description: The signature/tag of the artifact for verification. This value was provided during upload and can be used by the client to verify artifact integrity.
              schema:
                type: string
            x-artifact-sha:
              description: The git SHA of the commit that produced this artifact. This value was provided during upload.
              schema:
                type: string
            x-artifact-dirty-hash:
              description: A hash summarizing uncommitted changes in the working tree when this artifact was produced. This value was provided during upload.
              schema:
                type: string
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: Gzip-compressed tarball containing the cached task outputs
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/ArtifactNotFound'
    put:
      operationId: uploadArtifact
      summary: Upload a cache artifact
      description: '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.'
      tags:
      - artifacts
      security:
      - bearerToken: []
      parameters:
      - name: Content-Length
        in: header
        required: true
        description: The artifact size in bytes
        schema:
          type: integer
          minimum: 0
      - name: x-artifact-duration
        in: header
        required: false
        description: The time taken to generate the artifact in milliseconds. This value is stored and returned when the artifact is downloaded.
        schema:
          type: integer
          minimum: 0
      - name: x-artifact-tag
        in: header
        required: false
        description: 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.
        schema:
          type: string
          maxLength: 600
      - name: x-artifact-sha
        in: header
        required: false
        description: 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.
        schema:
          type: string
      - name: x-artifact-dirty-hash
        in: header
        required: false
        description: 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.
        schema:
          type: string
      - $ref: '#/components/parameters/ArtifactClientCI'
      - $ref: '#/components/parameters/ArtifactClientInteractive'
      requestBody:
        required: true
        description: The artifact data as a gzip-compressed tarball
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Artifact uploaded successfully (alternative success response)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactUploadResponse'
        '202':
          description: Artifact accepted for storage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactUploadResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /artifacts:
    post:
      operationId: queryArtifacts
      summary: Query artifact information
      description: 'Query information about multiple artifacts by their hashes. Returns metadata about each artifact including size, task duration, and tag.


        This endpoint is optional for basic cache functionality but enables optimized cache fetching by allowing the client to query multiple artifacts in a single request.'
      tags:
      - artifacts
      security:
      - bearerToken: []
      parameters:
      - $ref: '#/components/parameters/TeamId'
      - $ref: '#/components/parameters/Slug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtifactQueryRequest'
      responses:
        '200':
          description: Artifact information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    CachingStatusResponse:
      type: object
      required:
      - status
      properties:
        status:
          $ref: '#/components/schemas/CachingStatus'
    ArtifactError:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - message
          properties:
            message:
              type: string
              description: Error message describing why the artifact information could not be retrieved
    CachingStatus:
      type: string
      enum:
      - disabled
      - enabled
      - over_limit
      - paused
      description: 'The status of remote caching for the authenticated principal.


        - `enabled`: Remote caching is enabled and available

        - `disabled`: Remote caching is disabled

        - `over_limit`: Remote caching is disabled due to usage limits (optional)

        - `paused`: Remote caching is temporarily paused (optional)'
    ArtifactInfo:
      type: object
      required:
      - size
      - taskDurationMs
      properties:
        size:
          type: integer
          description: The size of the artifact in bytes
        taskDurationMs:
          type: integer
          description: The time taken to generate the artifact in milliseconds
        tag:
          type: string
          description: The artifact tag/signature for verification
    ArtifactQueryResponse:
      type: object
      additionalProperties:
        nullable: true
        oneOf:
        - $ref: '#/components/schemas/ArtifactInfo'
        - $ref: '#/components/schemas/ArtifactError'
      description: A map of artifact hashes to their information. The value is `null` if the artifact was not found.
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: A machine-readable error code
        message:
          type: string
          description: A human-readable error message
    ArtifactUploadResponse:
      type: object
      required:
      - urls
      properties:
        urls:
          type: array
          items:
            type: string
            format: uri
          description: Array of URLs where the artifact was stored. Implementers can return the storage location(s) for debugging purposes.
    ArtifactQueryRequest:
      type: object
      required:
      - hashes
      properties:
        hashes:
          type: array
          items:
            type: string
          description: Array of artifact hashes to query
  parameters:
    ArtifactClientInteractive:
      name: x-artifact-client-interactive
      in: header
      required: false
      description: Indicates whether the client is running in an interactive shell. `1` for interactive, `0` for non-interactive (CI/scripts).
      schema:
        type: integer
        enum:
        - 0
        - 1
    TeamId:
      name: teamId
      in: query
      required: false
      description: The team identifier to perform the request on behalf of. Used for multi-tenant cache implementations where artifacts are scoped to teams.
      schema:
        type: string
    Slug:
      name: slug
      in: query
      required: false
      description: The team slug to perform the request on behalf of. Alternative to `teamId` for identifying the team.
      schema:
        type: string
    ArtifactClientCI:
      name: x-artifact-client-ci
      in: header
      required: false
      description: 'The continuous integration or delivery environment where this artifact operation is being performed. Examples: `github-actions`, `circleci`, `jenkins`.'
      schema:
        type: string
        maxLength: 50
    ArtifactHash:
      name: hash
      in: path
      required: true
      description: The artifact hash. This is a content-addressable hash that uniquely identifies the cached artifact based on task inputs.
      schema:
        type: string
        pattern: ^[a-fA-F0-9]+$
        minLength: 1
  responses:
    Forbidden:
      description: Forbidden. The authenticated user does not have permission to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ArtifactNotFound:
      description: Artifact not found. No artifact with the specified hash exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized. The request is missing a valid authentication token or the token is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request. One or more of the provided values in the request query, headers, or body is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      description: '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'