# 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.3.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.3.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.3.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.3.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"]}}}}
```

## 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.3.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"]}}}}
```