# ctx.kv()

> Reference for ctx.kv(), covering the project-scoped key-value API: getItem, setItem, hasItem, and removeItem.

`ctx.kv()` returns the project-scoped key-value store. Call it with no arguments. Every function in the project reads and writes the same store.

## Signature

```typescript
kv(): KeyValueStore
```

Scope behavior and limits live in [the key-value store guide](/documentation/guides/key-value-store/).

## KeyValueStore

```typescript
interface KeyValueStore {
  getItem<T = unknown>(key: string): Promise<T | null>;
  setItem(key: string, value: unknown, opts?: { ttl?: number | null }): Promise<void>;
  removeItem(key: string): Promise<void>;
  hasItem(key: string): Promise<boolean>;
}
```

| Method | Returns | Notes |
|---|---|---|
| `getItem<T>(key)` | `Promise<T \| null>` | `null` when the key is missing. A stored JSON `null` also reads as `null`; use `hasItem` to disambiguate. |
| `setItem(key, value, opts?)` | `Promise<void>` | Accepts any JSON-serializable value. Pass `opts.ttl` in seconds to set an expiry; see below. |
| `removeItem(key)` | `Promise<void>` | Deletes the key. |
| `hasItem(key)` | `Promise<boolean>` | Existence check without fetching the value. |

## Setting an expiry

`setItem` takes an optional third argument, `{ ttl }`, a time to live in seconds:

```typescript
await kv.setItem('session:abc', data, { ttl: 3600 });
```

| `ttl` | Effect |
|---|---|
| A positive integer | Deletes the key that many seconds after the write. |
| `null` | Clears any existing expiry. |
| Omitted | Leaves any existing expiry unchanged. |

`ttl` must be a positive integer, with no maximum. See the [key-value store guide](/documentation/guides/key-value-store/#expiring-keys-with-a-ttl) for the full behavior.

## Example

```typescript
// functions/api/v1/flags.get.ts
import { defineFunction } from '@trayai/helix-sdk';

export default defineFunction(async (ctx) => {
  const kv = ctx.kv();

  let flags = await kv.getItem<Record<string, boolean>>('feature_flags');
  if (!flags) {
    flags = { beta: false };
    await kv.setItem('feature_flags', flags);
  }

  return { flags };
});
```

---

Canonical: https://helix.tray.ai/documentation/reference/context/kv/
Any link on this page is available as markdown by appending .md to its URL.
Full corpus: https://helix.tray.ai/documentation/llms-full.txt