# Operate on a KV namespace

Source: https://docs.wabe.sh/api-reference/operations/keyvalue/

`POST https://api.wabe.sh/v1/disks/{disk}/kv/{namespace}`

Keys: 16 KiB; values: 1 MiB; encoded batches and JSON bodies: 8 MiB. Scan stays within the namespace and uses byte order with an exclusive after cursor sharing the prefix. TTL is unsupported. Mutations never trigger flush; optional remote mode waits for background/explicit persistence.

## Authorization

Project API key from the Wabe Dashboard or actor runtime access token for the disk URL supplied by the broker.

## Parameters

- `disk` (path, string, required) — Project disk name, or the disk ID in the actor runtime disk URL.

- `namespace` (path, string, required) — Namespace on this disk.

## Request body

`application/json`

Example

```json
{
  "op": "scan",
  "prefix": "greet",
  "limit": 10
}
```

Schema

```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "op": {
          "const": "get"
        },
        "key": {
          "oneOf": [
            {
              "type": "string",
              "maxLength": 16384,
              "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
            },
            {
              "type": "object",
              "properties": {
                "base64": {
                  "type": "string",
                  "contentEncoding": "base64",
                  "maxLength": 21848
                }
              },
              "required": [
                "base64"
              ],
              "additionalProperties": false
            }
          ],
          "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
          "x-max-decoded-bytes": 16384
        }
      },
      "required": [
        "op",
        "key"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "op": {
          "const": "exists"
        },
        "key": {
          "oneOf": [
            {
              "type": "string",
              "maxLength": 16384,
              "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
            },
            {
              "type": "object",
              "properties": {
                "base64": {
                  "type": "string",
                  "contentEncoding": "base64",
                  "maxLength": 21848
                }
              },
              "required": [
                "base64"
              ],
              "additionalProperties": false
            }
          ],
          "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
          "x-max-decoded-bytes": 16384
        }
      },
      "required": [
        "op",
        "key"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "op": {
          "const": "delete"
        },
        "key": {
          "oneOf": [
            {
              "type": "string",
              "maxLength": 16384,
              "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
            },
            {
              "type": "object",
              "properties": {
                "base64": {
                  "type": "string",
                  "contentEncoding": "base64",
                  "maxLength": 21848
                }
              },
              "required": [
                "base64"
              ],
              "additionalProperties": false
            }
          ],
          "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
          "x-max-decoded-bytes": 16384
        }
      },
      "required": [
        "op",
        "key"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "op": {
          "const": "put"
        },
        "key": {
          "oneOf": [
            {
              "type": "string",
              "maxLength": 16384,
              "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
            },
            {
              "type": "object",
              "properties": {
                "base64": {
                  "type": "string",
                  "contentEncoding": "base64",
                  "maxLength": 21848
                }
              },
              "required": [
                "base64"
              ],
              "additionalProperties": false
            }
          ],
          "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
          "x-max-decoded-bytes": 16384
        },
        "value": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "type": {
                  "const": "text"
                },
                "value": {
                  "type": "string"
                }
              },
              "required": [
                "type",
                "value"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "const": "json"
                },
                "value": {}
              },
              "required": [
                "type",
                "value"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "type": {
                  "const": "bytes"
                },
                "value": {
                  "type": "string",
                  "contentEncoding": "base64",
                  "maxLength": 1398104
                }
              },
              "required": [
                "type",
                "value"
              ],
              "additionalProperties": false
            }
          ],
          "description": "At most 1048576 stored UTF-8/decoded payload bytes, excluding the storage type header.",
          "x-max-stored-bytes": 1048576
        }
      },
      "required": [
        "op",
        "key",
        "value"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "op": {
          "const": "batch"
        },
        "operations": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "op": {
                    "const": "put"
                  },
                  "key": {
                    "oneOf": [
                      {
                        "type": "string",
                        "maxLength": 16384,
                        "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
                      },
                      {
                        "type": "object",
                        "properties": {
                          "base64": {
                            "type": "string",
                            "contentEncoding": "base64",
                            "maxLength": 21848
                          }
                        },
                        "required": [
                          "base64"
                        ],
                        "additionalProperties": false
                      }
                    ],
                    "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
                    "x-max-decoded-bytes": 16384
                  },
                  "value": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "type": {
                            "const": "text"
                          },
                          "value": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "type",
                          "value"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "type": {
                            "const": "json"
                          },
                          "value": {}
                        },
                        "required": [
                          "type",
                          "value"
                        ],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "type": {
                            "const": "bytes"
                          },
                          "value": {
                            "type": "string",
                            "contentEncoding": "base64",
                            "maxLength": 1398104
                          }
                        },
                        "required": [
                          "type",
                          "value"
                        ],
                        "additionalProperties": false
                      }
                    ],
                    "description": "At most 1048576 stored UTF-8/decoded payload bytes, excluding the storage type header.",
                    "x-max-stored-bytes": 1048576
                  }
                },
                "required": [
                  "op",
                  "key",
                  "value"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "op": {
                    "const": "delete"
                  },
                  "key": {
                    "oneOf": [
                      {
                        "type": "string",
                        "maxLength": 16384,
                        "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
                      },
                      {
                        "type": "object",
                        "properties": {
                          "base64": {
                            "type": "string",
                            "contentEncoding": "base64",
                            "maxLength": 21848
                          }
                        },
                        "required": [
                          "base64"
                        ],
                        "additionalProperties": false
                      }
                    ],
                    "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
                    "x-max-decoded-bytes": 16384
                  }
                },
                "required": [
                  "op",
                  "key"
                ],
                "additionalProperties": false
              }
            ]
          }
        }
      },
      "required": [
        "op",
        "operations"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "op": {
          "const": "scan"
        },
        "prefix": {
          "oneOf": [
            {
              "type": "string",
              "maxLength": 16384,
              "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
            },
            {
              "type": "object",
              "properties": {
                "base64": {
                  "type": "string",
                  "contentEncoding": "base64",
                  "maxLength": 21848
                }
              },
              "required": [
                "base64"
              ],
              "additionalProperties": false
            }
          ],
          "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
          "x-max-decoded-bytes": 16384
        },
        "after": {
          "oneOf": [
            {
              "type": "string",
              "maxLength": 16384,
              "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
            },
            {
              "type": "object",
              "properties": {
                "base64": {
                  "type": "string",
                  "contentEncoding": "base64",
                  "maxLength": 21848
                }
              },
              "required": [
                "base64"
              ],
              "additionalProperties": false
            }
          ],
          "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
          "x-max-decoded-bytes": 16384
        },
        "limit": {
          "type": "integer",
          "minimum": 0
        },
        "reverse": {
          "type": "boolean",
          "default": false
        }
      },
      "required": [
        "op"
      ],
      "additionalProperties": false
    }
  ],
  "discriminator": {
    "propertyName": "op"
  }
}
```

## Responses

### 200

JSON response for get/exists/put/delete/batch, NDJSON entries for scan. Missing get returns found:false with HTTP 200.

`application/json`

Schema

```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "success": {
          "const": true
        }
      },
      "required": [
        "success"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "exists": {
          "type": "boolean"
        }
      },
      "required": [
        "exists"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "found": {
          "const": false
        }
      },
      "required": [
        "found"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "found": {
          "const": true
        },
        "entry": {
          "type": "object",
          "properties": {
            "key": {
              "oneOf": [
                {
                  "type": "string",
                  "maxLength": 16384,
                  "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
                },
                {
                  "type": "object",
                  "properties": {
                    "base64": {
                      "type": "string",
                      "contentEncoding": "base64",
                      "maxLength": 21848
                    }
                  },
                  "required": [
                    "base64"
                  ],
                  "additionalProperties": false
                }
              ],
              "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
              "x-max-decoded-bytes": 16384
            },
            "value": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "const": "text"
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "type",
                    "value"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "const": "json"
                    },
                    "value": {}
                  },
                  "required": [
                    "type",
                    "value"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "properties": {
                    "type": {
                      "const": "bytes"
                    },
                    "value": {
                      "type": "string",
                      "contentEncoding": "base64",
                      "maxLength": 1398104
                    }
                  },
                  "required": [
                    "type",
                    "value"
                  ],
                  "additionalProperties": false
                }
              ],
              "description": "At most 1048576 stored UTF-8/decoded payload bytes, excluding the storage type header.",
              "x-max-stored-bytes": 1048576
            },
            "revision": {
              "type": "string",
              "pattern": "^[0-9]+$",
              "description": "Opaque decimal sequence string."
            }
          },
          "required": [
            "key",
            "value",
            "revision"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "found",
        "entry"
      ],
      "additionalProperties": false
    }
  ]
}
```

`application/x-ndjson`

Example

```text
{"key":"greeting","value":{"type":"text","value":"Hello"},"revision":"7"}
```

Schema

```json
{
  "type": "string",
  "x-record-schema": "#/components/schemas/KvEntry"
}
```

Stream record schema

```json
{
  "type": "object",
  "properties": {
    "key": {
      "oneOf": [
        {
          "type": "string",
          "maxLength": 16384,
          "description": "UTF-8 key, at most 16 KiB of encoded bytes. Empty is allowed."
        },
        {
          "type": "object",
          "properties": {
            "base64": {
              "type": "string",
              "contentEncoding": "base64",
              "maxLength": 21848
            }
          },
          "required": [
            "base64"
          ],
          "additionalProperties": false
        }
      ],
      "description": "At most 16384 decoded bytes; string and binary encodings of identical bytes identify the same key.",
      "x-max-decoded-bytes": 16384
    },
    "value": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "text"
            },
            "value": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "value"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "json"
            },
            "value": {}
          },
          "required": [
            "type",
            "value"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "bytes"
            },
            "value": {
              "type": "string",
              "contentEncoding": "base64",
              "maxLength": 1398104
            }
          },
          "required": [
            "type",
            "value"
          ],
          "additionalProperties": false
        }
      ],
      "description": "At most 1048576 stored UTF-8/decoded payload bytes, excluding the storage type header.",
      "x-max-stored-bytes": 1048576
    },
    "revision": {
      "type": "string",
      "pattern": "^[0-9]+$",
      "description": "Opaque decimal sequence string."
    }
  },
  "required": [
    "key",
    "value",
    "revision"
  ],
  "additionalProperties": false
}
```

### 400

Invalid input, query, name or source.

`text/plain`

Schema

```json
{
  "type": "string"
}
```

### 401

Missing, invalid or revoked project API key, or an invalid runtime access token.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```

### 403

Actor runtime token does not authorize this disk or instance generation.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```

### 404

Disk not found in this project.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```

### 413

KV size or request-body limit exceeded.

`text/plain`

Schema

```json
{
  "type": "string"
}
```

### 415

KV body requires application/json.

`text/plain`

Schema

```json
{
  "type": "string"
}
```

### 422

KV JSON shape or operation is unsupported.

`text/plain`

Schema

```json
{
  "type": "string"
}
```

### 500

Storage, I/O or corruption failure.

`text/plain`

Schema

```json
{
  "type": "string"
}
```

### 503

Disk unavailable.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```