Agentuity Documentation

Store and retrieve arbitrary data by key within namespaces.

Region

https://catalyst-usw.agentuity.cloud

Authentication

All requests require a Bearer token. Pass your SDK key in the Authorization header.

Header	Value
`Authorization`	`Bearer YOUR_SDK_KEY`

You can find your SDK key in the Agentuity Console under your project settings.

Get Value

Retrieve a stored value by its namespace and key. Returns the raw value with the original content type.

GET/kv/{namespace}/{key}

https://catalyst-usw.agentuity.cloud/kv/{namespace}/{key}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace name
`key`	string	Yes	The key to retrieve

Response

Returns the raw stored value with the original content type. The response body is the value itself (not wrapped in JSON).

Status	Description
200	Value found and returned
401	Unauthorized — invalid or missing API key
404	Key does not exist in the namespace

Response Headers

Header	Description
`Content-Type`	MIME type of the stored value (e.g., `application/json`, `text/plain`, `application/octet-stream`)
`x-expires-at`	ISO 8601 expiration timestamp. Omitted if the key does not expire.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/kv/my-namespace/user-123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Store Value

Store a value in key-value storage. The namespace is auto-created if it doesn't exist. Set the Content-Type header to match your data format.

PUT/kv/{namespace}/{key}[/{ttl}]

https://catalyst-usw.agentuity.cloud/kv/{namespace}/{key}[/{ttl}]

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace name (auto-created if not exists)
`key`	string	Yes	The key to store the value under
`ttl`	number	No	Optional TTL in seconds (60–31,536,000). Omit for namespace default. Use `0` for no expiration.

Request Body

The raw value to store. Can be any content type — JSON, text, or binary.

Response

Empty response on success.

Status	Description
200	Value stored successfully
401	Unauthorized — invalid or missing API key
402	Payment required — upgrade to a paid plan

Notes

TTL behavior:

Omitted: Key inherits namespace default TTL (7 days if not configured)
0: Key never expires
60–31,536,000: Expires after specified seconds (values outside range are clamped)

Example

curl -X PUT 'https://catalyst-usw.agentuity.cloud/kv/my-namespace/user-123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Alice",
  "email": "alice@example.com"
}'

Delete Value

Delete a specific key from a namespace.

DELETE/kv/{namespace}/{key}

https://catalyst-usw.agentuity.cloud/kv/{namespace}/{key}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace name
`key`	string	Yes	The key to delete

Response

Empty response on success.

Status	Description
200	Key deleted successfully
401	Unauthorized

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/kv/my-namespace/user-123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Search Keys

Search for keys matching a keyword within a namespace. Returns matching keys with their values and metadata.

GET/kv/search/{namespace}/{keyword}

https://catalyst-usw.agentuity.cloud/kv/search/{namespace}/{keyword}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace to search in
`keyword`	string	Yes	The keyword to search for in key names

Response

JSON object mapping key names to their values and metadata.

Status	Description
200	Search results returned
401	Unauthorized

Response Fields

Field	Type	Description
`{key}.value`	any	The stored value (base64-encoded for binary)
`{key}.contentType`	string	MIME type of the stored value
`{key}.size`	number	Size in bytes
`{key}.expiresAt`	string \| null	ISO 8601 expiration timestamp
`{key}.firstUsed`	number \| null	Unix timestamp (ms) of first access
`{key}.lastUsed`	number \| null	Unix timestamp (ms) of last access
`{key}.count`	number \| null	Number of times accessed

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/kv/search/my-namespace/user' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Keys

Get all key names in a namespace.

GET/kv/keys/{namespace}

https://catalyst-usw.agentuity.cloud/kv/keys/{namespace}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace to list keys from

Response

JSON array of key name strings.

Status	Description
200	Key list returned
401	Unauthorized

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/kv/keys/my-namespace' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Namespace Stats

Get statistics for a specific namespace including record count and size.

GET/kv/stats/{namespace}

https://catalyst-usw.agentuity.cloud/kv/stats/{namespace}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace to get stats for

Response

JSON object with namespace statistics.

Status	Description
200	Stats returned
401	Unauthorized

Response Fields

Field	Type	Description
`sum`	number	Total size in bytes for the namespace.
`count`	number	Number of records in the namespace.
`createdAt`	number	Unix timestamp (milliseconds) when the namespace was created. (optional)
`lastUsedAt`	number	Unix timestamp (milliseconds) when the namespace was last used. (optional)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/kv/stats/my-namespace' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List All Namespace Stats

Get statistics for all namespaces with optional pagination and filtering.

GET/kv/stats

https://catalyst-usw.agentuity.cloud/kv/stats

Parameters

query

Name	Type	Required	Description
`limit`	number	No	Maximum namespaces to return (default: 100, max: 1000)
`offset`	number	No	Number of namespaces to skip (default: 0)
`sort`	string	No	Sort field: `name`, `size`, `records`, `created`, or `lastUsed`
`direction`	string	No	Sort direction: `asc` or `desc` (default: `desc`)
`name`	string	No	Filter namespaces by name substring

Response

Paginated response with namespace statistics.

Status	Description
200	Stats returned
401	Unauthorized

Response Fields

Field	Type	Description
`namespaces`	object	Map of namespace names to their statistics
`total`	number	Total number of namespaces across all pages
`limit`	number	Number of namespaces requested per page
`offset`	number	Number of namespaces skipped
`hasMore`	boolean	Whether there are more namespaces available

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/kv/stats?limit=10&sort=size&direction=desc' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Namespaces

Get all namespace names (up to 1000, ordered by creation date, most recent first).

GET/kv/namespaces

https://catalyst-usw.agentuity.cloud/kv/namespaces

Response

JSON array of namespace name strings.

Status	Description
200	Namespace list returned
401	Unauthorized

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/kv/namespaces' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Create Namespace

Create a new namespace with optional default TTL configuration.

POST/kv/{namespace}

https://catalyst-usw.agentuity.cloud/kv/{namespace}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace name to create

Request Body

Optional JSON body with namespace configuration.

Field	Type	Description
`default_ttl_seconds`	number	Default TTL for keys in this namespace (in seconds). If omitted, defaults to 7 days (604,800). Use 0 for keys that never expire. (optional)

Response

Empty response on success.

Status	Description
200	Namespace created successfully
401	Unauthorized
402	Payment required

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/kv/my-namespace' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "default_ttl_seconds": 86400
}'

Delete Namespace

Delete an entire namespace and all its keys.

DELETE/kv/{namespace}

https://catalyst-usw.agentuity.cloud/kv/{namespace}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace to delete

Response

Empty response on success.

Status	Description
200	Namespace deleted successfully
401	Unauthorized

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/kv/my-namespace' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'