What is the Blob Store?

FreeClimb's Blob Store gives your application a simple way to persist and retrieve arbitrary JSON Blobs using the FreeClimb REST API. Unlike in-call features such as PerCL commands or Audio Streaming, the Blob Store operates independently of any active call. Your application can write blobs at any point and read it back later across requests, across calls, or from an entirely separate system.

This approach is designed for applications that need to carry state between call events without relying on an external database or third-party caching layer.

Why you’ll use it

• In‑call state handling – While a call is in progress you can write a blob (e.g., the caller’s current step, a verification token, or a temporary flag) and read it back on the next callback, without needing a separate database.
• Cross‑request persistence – The data lives for the lifetime of the call (or until you delete it), allowing you to pass information between the many HTTP requests that FreeClimb makes during a single call flow.
• Multi‑call or external access – Because the API is not tied to a call, you can also read or write blobs from other calls, background jobs, or third‑party systems when you need longer‑term or cross‑call storage.

How the Blob Store works

Your application interacts with the Blob Store through standard REST API calls (POST, GET, PATCH, PUT, DELETE) to the FreeClimb Blobs endpoint. Each stored object, called a blob, is a JSON object that FreeClimb holds temporarily on your behalf.

When your application creates a blob, FreeClimb stores it and returns a unique blobId. You can also assign an alias, such as a call ID or conversation ID, so your application can look up the blob later without needing to track the system-generated ID.

Blobs are ephemeral by design. They automatically expire and are deleted after 9 hours by default. If your application needs the blob to persist longer, you can set a custom expiration up to a maximum of 48 hours.

Your application has full control over the blob. It can update specific fields within a blob (PATCH), replace the entire blob (PUT), delete individual keys, or delete the blob entirely.

Blob flow at a glance

A typical Blob Store interaction follows this pattern:

┌──────────────────────┐      ┌───────────────────────┐
│ Incoming call (PerCL)│──►   │ POST /Blobs (store)   │
└──────────────────────┘      └───────────────────────┘
          │                               │
          ▼                               ▼
┌─────────────────────┐      ┌───────────────────────┐
│ Later in the same   │      │ GET /Blobs (retrieve) │
│ call or next call   │◄─────│  using alias or ID    │
└─────────────────────┘      └───────────────────────┘
          │
          ▼
┌──────────────────────┐
│ Blob expiresup to 48h│
└──────────────────────┘   (no manual cleanup required) 

1. Your application receives an incoming call and processes it via PerCL as usual.
2. During or after the call, your application sends a POST request to the Blobs API to store relevant blob (e.g., caller preferences, IVR selections, or session context), using the call ID as the alias.
3. FreeClimb stores the blob and returns the full object, including the blobId, timestamps, and expiration.
4. On a subsequent call or callback, your application sends a GET request using the alias to retrieve the stored blob.
5. Your application uses the retrieved blob to personalize the call flow, route the caller, or pick up where a previous interaction left off.
6. The blob expires automatically after the configured TTL. No cleanup is required.

When to use the Blob Store

The Blob Store is designed for scenarios where your application needs to carry context between separate API requests or call events without managing its own persistence layer.

What to know before you start

Before using the Blob Store, make sure your application is prepared for the following:

• Access must be enabled. The Blob Store is gated by an account-level setting. Contact FreeClimb support to have it activated for your account.
• Authentication uses your existing FreeClimb credentials. API requests are authenticated with your Account ID and API Key via HTTP Basic Auth (the same credentials you use for other FreeClimb APIs).
• Blobs must be valid JSON objects. The top-level structure must be a JSON object (), and top-level keys may only contain letters, numbers, hyphens, and underscores.
• Size limits apply. Each individual blob can be up to 512 KiB. The total storage across all blobs on your account is capped at 10 MiB.
• Blob is temporary. Blobs expire automatically (default 9 hours, maximum 48 hours). The Blob Store is not intended for permanent storage.
• Aliases are unique per account. If you assign an alias to a blob, that alias must be unique within your account. This makes aliases ideal for keys like call IDs or session identifiers.

- [ ] **Blob Store enabled** – open a support ticket if you haven’t gotten the feature flag.
- [ ] **Credentials ready** – Account SID & API Key (Basic Auth).
- [ ] **JSON payload** – top‑level must be an object; keys = ^[a-zA-Z0-9_-]{1,64}$.
- [ ] **Size limits** – ≤ 512 KiB per blob, ≤ 10 MiB total per account.
- [ ] **TTL decision** – default 9 h, or set a custom TTL (max 48 h) at creation.
- [ ] **Alias uniqueness** – ensure the alias you choose isn’t already in use.