> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/api-reference/key-value.md).

# 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.20.1"},"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.20.1"},"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.20.1"},"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.20.1"},"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.20.1"},"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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.