> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springwinter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Caches API: Manage Valkey Instances in AWS

> REST endpoints to provision, configure, and delete Valkey (Redis-compatible) caches inside a Springwinter project running in your AWS account.

The Caches API lets you provision, configure, and delete Valkey (Redis-compatible) caches inside your project. Each cache runs in your AWS account and is accessible from web servers and workers in the same project over TLS — no password required. Use these endpoints to create a cache, adjust its storage limit, retrieve CloudWatch metrics, and estimate spend.

## List Caches

**GET /api/projects/{project_id}/redis**

Return all Valkey caches that exist within the specified project.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/projects/proj_abc123/redis \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "caches": [
      {
        "id": "cache_xyz789",
        "status": "available",
        "endpoint": "cache-xyz789.internal.springwinter.dev:6379",
        "storage_limit_mb": 512,
        "created_at": "2025-01-15T10:30:00Z",
        "updated_at": "2025-01-15T10:35:22Z"
      }
    ]
  }
  ```
</CodeGroup>

<ResponseField name="caches" type="array">
  Array of cache objects for the project. Each object has the same shape as the single-cache GET response.
</ResponseField>

***

## Enable a Cache

<ParamField path="project_id" type="string" required>
  The ID of the project in which to create the cache.
</ParamField>

**POST /api/projects/{project_id}/redis**

Create and enable a new Valkey cache for the project.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://springwinter.dev/api/projects/proj_abc123/redis \
    -H "Authorization: Bearer swt_yourtoken" \
    -H "Content-Type: application/json" \
    -d '{ "storage_limit_mb": 512 }'
  ```

  ```json Response theme={null}
  {
    "id": "cache_xyz789",
    "status": "creating",
    "endpoint": "cache-xyz789.internal.springwinter.dev:6379",
    "storage_limit_mb": 512,
    "created_at": "2025-01-15T10:30:00Z"
  }
  ```
</CodeGroup>

<ParamField body="storage_limit_mb" type="integer" required>
  Maximum memory the cache may use, in megabytes. Minimum: `128`. Use a power of two for best alignment with Valkey internals (e.g. `256`, `512`, `1024`).
</ParamField>

<ResponseField name="id" type="string">
  Unique identifier for the cache resource.
</ResponseField>

<ResponseField name="status" type="string">
  Provisioning state. One of `creating`, `available`, `modifying`, or `deleting`.
</ResponseField>

<ResponseField name="endpoint" type="string">
  Internal DNS hostname and port your services use to connect. Only reachable from within the same project.
</ResponseField>

<ResponseField name="storage_limit_mb" type="integer">
  Configured memory limit in megabytes.
</ResponseField>

***

## Get a Cache

**GET /api/projects/{project_id}/redis/{id}**

Return the current configuration and status of a Valkey cache.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/projects/proj_abc123/redis/cache_xyz789 \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "id": "cache_xyz789",
    "status": "available",
    "endpoint": "cache-xyz789.internal.springwinter.dev:6379",
    "storage_limit_mb": 512,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:35:22Z"
  }
  ```
</CodeGroup>

<ResponseField name="id" type="string">Unique cache identifier.</ResponseField>
<ResponseField name="status" type="string">Current lifecycle state of the cache.</ResponseField>
<ResponseField name="endpoint" type="string">Internal TLS endpoint your services connect to.</ResponseField>
<ResponseField name="storage_limit_mb" type="integer">Configured memory limit in megabytes.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 timestamp of when the cache was created.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 timestamp of the most recent update.</ResponseField>

***

## Update a Cache

**PATCH /api/projects/{project_id}/redis/{id}**

Change the storage limit of an existing cache. The cache remains available during the modification.

<CodeGroup>
  ```bash Request theme={null}
  curl -X PATCH https://springwinter.dev/api/projects/proj_abc123/redis/cache_xyz789 \
    -H "Authorization: Bearer swt_yourtoken" \
    -H "Content-Type: application/json" \
    -d '{ "storage_limit_mb": 1024 }'
  ```

  ```json Response theme={null}
  {
    "id": "cache_xyz789",
    "status": "modifying",
    "storage_limit_mb": 1024
  }
  ```
</CodeGroup>

<ParamField body="storage_limit_mb" type="integer" required>
  New memory limit in megabytes. Must be greater than or equal to the current limit — downsizing is not supported.
</ParamField>

***

## Delete a Cache

**DELETE /api/projects/{project_id}/redis/{id}**

Permanently delete a Valkey cache. All data stored in the cache is lost.

<Warning>
  Deleting a cache destroys all cached data immediately. Any web servers or workers that connect to the cache endpoint will begin receiving connection errors. This action cannot be undone.
</Warning>

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE https://springwinter.dev/api/projects/proj_abc123/redis/cache_xyz789 \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "id": "cache_xyz789",
    "status": "deleting"
  }
  ```
</CodeGroup>

***

## Get Cache Cost Estimate

**GET /api/projects/{project_id}/redis/{id}/cost**

Return the estimated AWS spend for this cache and a direct link to AWS Cost Explorer for a full cost breakdown.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/projects/proj_abc123/redis/cache_xyz789/cost \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "cost_explorer_url": "https://us-east-1.console.aws.amazon.com/cost-management/home#/custom?...",
    "estimated_monthly_usd": 18.40,
    "month_to_date_usd": 6.12,
    "currency": "USD"
  }
  ```
</CodeGroup>

<ResponseField name="cost_explorer_url" type="string">
  A direct URL to AWS Cost Explorer pre-filtered for this cache. Open it in your browser while logged in to your AWS account for a full native cost breakdown.
</ResponseField>

<ResponseField name="estimated_monthly_usd" type="number">
  Projected full-month cost based on the current configuration and usage, sourced from AWS Cost Explorer.
</ResponseField>

<ResponseField name="month_to_date_usd" type="number">
  Actual AWS spend recorded so far this calendar month.
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code for all cost values. Always `"USD"`.
</ResponseField>

***

## Get Cache Metrics

**GET /api/projects/{project_id}/redis/{id}/metrics**

Return CloudWatch metrics for the cache over a recent time window.

<CodeGroup>
  ```bash Request theme={null}
  curl https://springwinter.dev/api/projects/proj_abc123/redis/cache_xyz789/metrics \
    -H "Authorization: Bearer swt_yourtoken"
  ```

  ```json Response theme={null}
  {
    "cache_hits": 48201,
    "cache_misses": 3104,
    "memory_used_bytes": 268435456,
    "curr_connections": 12,
    "period_seconds": 3600
  }
  ```
</CodeGroup>

<ResponseField name="cache_hits" type="integer">Number of successful key lookups in the reporting period.</ResponseField>
<ResponseField name="cache_misses" type="integer">Number of key lookups that returned a miss.</ResponseField>
<ResponseField name="memory_used_bytes" type="integer">Bytes of memory currently in use by cached data.</ResponseField>
<ResponseField name="curr_connections" type="integer">Number of active client connections at the end of the period.</ResponseField>
<ResponseField name="period_seconds" type="integer">Length of the reporting window in seconds.</ResponseField>

***

<Note>
  The cache endpoint is reachable from web servers and workers within the same project over TLS on port 6379. No username or password is required — network-level access controls restrict connectivity to your project's resources only.
</Note>