Native Resources API

Access user-defined Cloudflare KV, D1, and Vectorize resources. All endpoints require Service Key authentication.

---

KV

POST /api/kv/:namespace

Action-based operations on a user-defined KV namespace. The namespace must be declared in config.kv.

Auth: Service Key required.

Action	Body Fields	Description
get	key	Get value by key
set	key, value, ttl?	Set value (TTL in seconds)
delete	key	Delete key
list	prefix?, limit?, cursor?	List keys

Examples:

Set a value:

{ "action": "set", "key": "user:123", "value": "cached-data", "ttl": 300 }

Get response:

{ "value": "cached-data" }

List response:

{ "keys": ["user:1", "user:2"], "cursor": null }

Delete request:

{ "action": "delete", "key": "user:123" }

Notes

• KV is eventually consistent and writes to the same key are limited to 1 per second.
• ttl uses KV expiration TTL semantics, so values less than 60 seconds are not supported by Cloudflare KV.

---

D1

POST /api/d1/:database

Execute SQL on a user-defined D1 database. The database must be declared in config.d1.

Auth: Service Key required.

Field	Type	Required	Description
query	string	Yes	SQL query
params	array	No	Parameter bindings

Request example:

{ "query": "SELECT * FROM events WHERE type = ? LIMIT 10", "params": ["click"] }

Delete example:

{ "query": "DELETE FROM events WHERE created_at < ?", "params": ["2025-01-01"] }

Response 200:

{
  "results": [{ "id": 1, "type": "click", "createdAt": "..." }],
  "meta": { "changes": 0, "duration": 1.23, "rows_read": 10, "rows_written": 0 }
}

---

Vectorize

POST /api/vectorize/:index

Action-based operations on a user-defined Vectorize index. The index must be declared in config.vectorize.

Auth: Service Key required.

Action	Body Fields	Description
upsert	vectors (array of {id, values, metadata?}), namespace?	Insert or replace vectors
insert	vectors (array of {id, values, metadata?}), namespace?	Insert only new vector IDs
search	vector, topK?, filter?, namespace?, returnValues?, returnMetadata?	Similarity search by vector values
queryById	vectorId, topK?, filter?, namespace?, returnValues?, returnMetadata?	Similarity search using an existing vector's ID
getByIds	ids (string array)	Retrieve vectors by ID
delete	ids (string array)	Delete vectors by ID
describe	(none)	Get index info: vectorCount, dimensions, metric

Search example:

{ "action": "search", "vector": [0.1, 0.2, 0.3], "topK": 5 }

Describe example:

{ "action": "describe" }

Delete example:

{ "action": "delete", "ids": ["doc-1", "doc-2"] }

Response 200:

{
  "vectorCount": 1500,
  "dimensions": 384,
  "metric": "cosine"
}

Notes

• Cloudflare Vectorize mutations are asynchronous. insert, upsert, and delete may take a few seconds to appear in queries.
• Namespace filtering works by default. Filtering on other metadata properties requires metadata indexes in Vectorize.
• Vectors written before a metadata index exists must be re-upserted before that property becomes filterable.
• EdgeBase may return a 409 if the underlying insert operation surfaces a conflict, but native Cloudflare Vectorize itself treats insert as “new IDs only”.