What is the FreeClimb JSON Blob Store?

The FreeClimb JSON 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 JSON 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.

Key use cases for storing in-call and cross-request state in FreeClimb

• In-Call Flow Persistence: Store temporary session data such as caller selections, verification tokens, or step flags and retrieve it across the sequential HTTP callbacks FreeClimb triggers during an active call, eliminating the need to spin up a external database or caching layer.
• Third Party State Management: Read and write state directly from third-party systems, background workers, webhooks, or external dashboards. This allows external platforms to push updates to active workflows or ingest call states in real time.
• Cross-Call Data Sharing: Pass state between independent call sessions, such as tracking caller history, sharing session identifiers across bridged calls, or managing global queue counters across concurrent streams.

How to create, retrieve, and expire JSON objects in FreeClimb JSON Blob Store

Your application interacts with the JSON Blob Store through standard REST API calls (POST, GET, PATCH, PUT, DELETE) to the FreeClimb JSON 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 JSON Blob Store interaction follows this pattern:

┌──────────────────────┐      ┌─────────────────────────┐
│ Incoming call (PerCL)│──►   │ POST /JSON Blobs (store)│
└──────────────────────┘      └─────────────────────────┘
          │                               
          ▼                               
┌─────────────────────┐      ┌───────────────────────┐
│ Later in the same   │      │ GET /Blobs (retrieve) │
│ call or next call   │─────►│  using alias or ID    │
└─────────────────────┘      └───────────────────────┘
          │
          ▼
┌───────────────────────┐
│ Blob expires up 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.

What are the best use cases and storage limits for FreeClimb JSON Blob Store?

The JSON 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 JSON Blob Store, make sure your application is prepared for the following:

• Access must be enabled. The JSON 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 JSON 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.

FreeClimb JSON Blob Store Integration Prerequisites & Checklist

- [ ] **JSON 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.