# Key Value

## Delete a key-value pair

> Permanently removes a key-value pair from storage. Returns 404 if the key does not exist. This operation cannot be undone. Only users with owner role or application tokens can perform this operation.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/key-value/{key}":{"delete":{"operationId":"KeyValueController_delete","summary":"Delete a key-value pair","description":"Permanently removes a key-value pair from storage. Returns 404 if the key does not exist. This operation cannot be undone. Only users with owner role or application tokens can perform this operation.","parameters":[{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":"The key-value pair has been successfully deleted."},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"The key was not found."},"500":{"description":"Internal server error."}},"tags":["Key Value"]}}}}
```

## Create a new key-value pair

> Creates a new key-value pair. Will fail if the key already exists. Use upsert endpoint to create or update. Values can be any JSON-serializable data. Optional TTL and tags can be specified.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/key-value":{"post":{"operationId":"KeyValueController_create","summary":"Create a new key-value pair","description":"Creates a new key-value pair. Will fail if the key already exists. Use upsert endpoint to create or update. Values can be any JSON-serializable data. Optional TTL and tags can be specified.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"responses":{"201":{"description":"The key-value pair has been successfully created.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"403":{"description":"Forbidden - Requires role: owner, application"},"409":{"description":"The key already exists."},"500":{"description":"Internal server error."}},"tags":["Key Value"]}}}}
```

## Create or update a key-value pair

> Creates a new key-value pair or updates an existing one. This is the preferred method for storing data when you want to ensure the value is saved regardless of whether the key exists.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/key-value/upsert":{"post":{"operationId":"KeyValueController_upsert","summary":"Create or update a key-value pair","description":"Creates a new key-value pair or updates an existing one. This is the preferred method for storing data when you want to ensure the value is saved regardless of whether the key exists.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"responses":{"200":{"description":"The key-value pair has been successfully created or updated.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"403":{"description":"Forbidden - Requires role: owner, application"},"500":{"description":"Internal server error."}},"tags":["Key Value"]}}}}
```

## Get the value for a given key

> Retrieves the value associated with the specified key. Returns 404 if the key does not exist. Expired keys (if TTL was set) are automatically removed and will return 404.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/key-value/{key}":{"get":{"operationId":"KeyValueController_read","summary":"Get the value for a given key","description":"Retrieves the value associated with the specified key. Returns 404 if the key does not exist. Expired keys (if TTL was set) are automatically removed and will return 404.","parameters":[{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"The value has been successfully retrieved."},"403":{"description":"Forbidden - Requires role: member, application"},"404":{"description":"The key was not found."},"500":{"description":"Internal server error."}},"tags":["Key Value"]}}}}
```

## Update the value for a given key

> Updates an existing key-value pair. Will fail with 404 if the key does not exist. Use this when you need to ensure the key exists before updating. TTL and tags can also be updated.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.9.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/key-value/{key}":{"put":{"operationId":"KeyValueController_update","summary":"Update the value for a given key","description":"Updates an existing key-value pair. Will fail with 404 if the key does not exist. Use this when you need to ensure the key exists before updating. TTL and tags can also be updated.","parameters":[{"name":"key","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string"}}}}}},"responses":{"200":{"description":"The value has been successfully updated.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}}}},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"The key was not found."},"500":{"description":"Internal server error."}},"tags":["Key Value"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/sfp-community/api-reference/key-value.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.