Get Started with the Blob Store

In this how-to guide, we will walk through storing, retrieving, updating, and deleting a blob using cURL commands against the FreeClimb Blobs API.

👍

You're ready for this how-to guide if you've got the following:

A FreeClimb account
The Blob Store feature enabled on your account (contact FreeClimb support to activate it)
Your Account ID and API Key (found on the FreeClimb Dashboard under API Keys)
cURL installed (or an API client such as Postman)

Step 1: Find your credentials

Every request to the Blob Store API authenticates with HTTP Basic Auth using your FreeClimb Account ID as the username and your API Key as the password.

You can find both values on the FreeClimb Dashboard under API Keys.

In the examples below, replace <account_id> with your Account ID and <api_key> with your API Key.

Step 2: Verify connectivity

Before creating any blob, confirm that your credentials work and you can reach the API. Make a simple GET request to the Blob Store list endpoint. You don’t need to provide an alias for this check; any list request will confirm connectivity. The he response will be an empty list:

curl "https://www.freeclimb.com/apiserver/Accounts/<account_id>/Blobs" \
     -u "<account_id>:<api_key>"

Expected response:

{
  "total": 0,
  "start": 0,
  "end": 0,
  "page": 0,
  "numPages": 1,
  "pageSize": 0,
  "nextPageUri": null,
  "blobs": []
}

If you see this response, your credentials are correct and connectivity is working.

Step 3: Create a blob

Store a JSON object by sending a POST request to the blobs endpoint. You can optionally include an alias (a human-readable key for looking up the blob later) and an expiresAt timestamp:

curl -X POST 'https://www.freeclimb.com/apiserver/Accounts/<account_id>/Blobs' \
  -u "<account_id>:<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "conv_2901k6ax4vvtfxtt6nb1yz5nb4xy",
    "blob": {
      "field0": "value0",
      "field1": "value1",
      "field2": "value2"
    }
  }'

Expected response:

{
  "revision": 1,
  "dateCreated": "2025-09-24T16:35:00.000Z",
  "dateUpdated": "2025-09-24T16:35:00.000Z",
  "expiresAt": "2025-09-25T01:35:00.000Z",
  "blobId": "BL65ee405737f661c9223ca7c6069fc1ddfd65f7cc",
  "accountId": "<account_id>",
  "alias": "conv_2901k6ax4vvtfxtt6nb1yz5nb4xy",
  "size": 42,
  "blob": {
    "field0": "value0",
    "field1": "value1",
    "field2": "value2"
  }
}

FreeClimb returns the full blob object, including the system-generated blobId, timestamps, and the default expiration (9 hours from creation). Note the blobId - you'll use it for updates and deletes.

Step 4: Retrieve your blob

You can retrieve a blob in two ways, by its blobId or by its alias.

By alias (useful when you've stored the call ID or conversation ID as the alias):

curl 'https://www.freeclimb.com/apiserver/Accounts/<account_id>/Blobs?alias=conv_2901k6ax4vvtfxtt6nb1yz5nb4xy' \
  -u "<account_id>:<api_key>"

By blobId (useful when you've stored the system-generated ID):

curl 'https://www.freeclimb.com/apiserver/Accounts/<account_id>/Blobs/<blob_id>' \
  -u "<account_id>:<api_key>"

Step 5: Update specific fields (PATCH)

To update individual fields within a blob without replacing the entire object, use PATCH. Fields you include will be added or overwritten; fields you omit will remain unchanged:

curl -X PATCH 'https://www.freeclimb.com/apiserver/Accounts/<account_id>/Blobs/<blob_id>' \
  -u "<account_id>:<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "blob": {
      "field0": "updated_value",
      "field3": "new_field"
    }
  }'

The response will show the merged result: field0 updated, field3 added, and field1 and field2 preserved. The revision number increments with each update.

Step 6: Replace a blob entirely (PUT)

To replace all fields within a blob, use PUT. This overwrites the entire blob contents. Any fields not included in the request body will be removed:

curl -X PUT 'https://www.freeclimb.com/apiserver/Accounts/<account_id>/Blobs/<blob_id>' \
  -u "<account_id>:<api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "blob": {
      "newField": "this is the only field now"
    }
  }'

Step 7: Delete keys or delete a blob

Delete specific keys from a blob by passing key query parameters to the DELETE endpoint. Keys that don't exist are silently ignored:

curl -X DELETE 'https://www.freeclimb.com/apiserver/Accounts/<account_id>/Blobs/<blob_id>?key=field1&key=field2' \
  -u "<account_id>:<api_key>"

Delete the entire blob by calling DELETE without any key parameters:

curl -X DELETE 'https://www.freeclimb.com/apiserver/Accounts/<account_id>/Blobs/<blob_id>' \
  -u "<account_id>:<api_key>"

API Reference

Limits and constraints