Datastore API

Store and retrieve key-value entries scoped to your organization.

List entries

GET /api/v1/datastore

Query parameters:

Parameter	Type	Description
namespace	string	Filter by namespace
prefix	string	Filter keys by prefix (case-sensitive)
page	integer	Page number (default: 1)
page_size	integer	Entries per page (default: 50)

curl "https://app.hooklistener.com/api/v1/datastore?namespace=production&prefix=config:&page=1&page_size=20" \
  -H "Authorization: Bearer hklst_your_api_key"

Response:

{
  "data": [
    {
      "id": "ds_abc123",
      "key": "config:api:timeout",
      "namespace": "production",
      "value": 30,
      "description": "API timeout in seconds",
      "expires_at": null,
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-03-15T10:00:00Z"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total_count": 1,
  "total_pages": 1
}

Get an entry

GET /api/v1/datastore/entries/:key

Query parameters:

Parameter	Type	Description
namespace	string	Namespace to look up (default: "default")

curl "https://app.hooklistener.com/api/v1/datastore/entries/config:api:timeout?namespace=production" \
  -H "Authorization: Bearer hklst_your_api_key"

Response:

{
  "data": {
    "id": "ds_abc123",
    "key": "config:api:timeout",
    "namespace": "production",
    "value": 30,
    "description": "API timeout in seconds",
    "expires_at": null,
    "created_at": "2026-03-15T10:00:00Z",
    "updated_at": "2026-03-15T10:00:00Z"
  }
}

Returns 404 if the entry does not exist or has expired.

Upsert an entry

PUT /api/v1/datastore/entries

Creates the entry if it doesn't exist, or updates the value, description, and expiration if it does.

curl -X PUT https://app.hooklistener.com/api/v1/datastore/entries \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "entry": {
      "key": "config:api:timeout",
      "namespace": "production",
      "value": 30,
      "description": "API timeout in seconds",
      "ttl_seconds": 86400
    }
  }'

Request body:

Field	Type	Required	Description
key	string	Yes	Entry key. 1–255 chars: a-z, A-Z, 0-9, _, ., -, :, /
namespace	string	No	Namespace (default: "default"). Same format as key
value	any	Yes	Any JSON value (max 64 KB encoded)
description	string	No	Human-readable note (max 1,000 chars)
ttl_seconds	integer	No	Time-to-live in seconds. Entry expires after this duration

Response: 200 OK with the created or updated entry.

Returns 403 if the Datastore feature is not available on your plan, or 422 if you've reached your plan's entry limit.

Delete an entry

DELETE /api/v1/datastore/entries/:key

Query parameters:

Parameter	Type	Description
namespace	string	Namespace of the entry (default: "default")

curl -X DELETE "https://app.hooklistener.com/api/v1/datastore/entries/config:api:timeout?namespace=production" \
  -H "Authorization: Bearer hklst_your_api_key"

Response: 200 OK with the deleted entry.

Returns 404 if the entry does not exist.

List namespaces

GET /api/v1/datastore/namespaces

Returns all distinct namespaces that contain at least one non-expired entry, sorted alphabetically.

curl https://app.hooklistener.com/api/v1/datastore/namespaces \
  -H "Authorization: Bearer hklst_your_api_key"

Response:

{
  "data": ["default", "production", "staging"]
}