Skip to content

API Reference

Jump to bottom
Temp edited this page Nov 22, 2025 · 2 revisions

API Reference

Complete API documentation for KV Manager endpoints.

Base URL

  • Production: Your Worker URL (e.g., https://kv-manager.yourteam.workers.dev)
  • Development: http://localhost:8787

Authentication

All production API requests require a valid Cloudflare Access JWT token.

Header:

cf-access-jwt-assertion: YOUR_JWT_TOKEN

Note: Authentication is bypassed for localhost requests in development.

Response Format

Success Response

{
  "success": true,
  "data": { ... }
}

Error Response

{
  "success": false,
  "error": "Error message"
}

Endpoints

Namespaces

List Namespaces

GET /api/namespaces

Response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "title": "my-namespace",
      "supports_url_encoding": true
    }
  ]
}

Create Namespace

POST /api/namespaces

Body:

{
  "title": "my-new-namespace"
}

Response:

{
  "success": true,
  "data": {
    "id": "...",
    "title": "my-new-namespace"
  }
}

Delete Namespace

DELETE /api/namespaces/:id

Response:

{
  "success": true
}

Rename Namespace

PATCH /api/namespaces/:id/rename

Body:

{
  "title": "new-namespace-name"
}

Response:

{
  "success": true
}

Get Namespace Info

GET /api/namespaces/:id/info

Response:

{
  "success": true,
  "data": {
    "id": "...",
    "title": "my-namespace",
    "keyCount": 1234,
    "firstAccessed": "2025-11-01T12:00:00.000Z",
    "lastAccessed": "2025-11-21T15:30:00.000Z"
  }
}

Keys

List Keys

GET /api/keys/:namespaceId/list?limit=100&cursor=optional

Query Parameters:

  • limit (optional) - Number of keys to return (default: 100, max: 1000)
  • cursor (optional) - Pagination cursor from previous response

Response:

{
  "success": true,
  "data": {
    "keys": [
      {
        "name": "user:123",
        "expiration": 1735689600,
        "metadata": {
          "type": "user"
        }
      }
    ],
    "cursor": "next_page_cursor",
    "list_complete": false
  }
}

Get Key

GET /api/keys/:namespaceId/:keyName

Response:

{
  "success": true,
  "data": {
    "value": "John Doe",
    "metadata": {
      "type": "user"
    }
  }
}

Create/Update Key

PUT /api/keys/:namespaceId/:keyName

Body:

{
  "value": "New value",
  "ttl": 3600,
  "metadata": {
    "type": "example"
  }
}

Fields:

  • value (required) - Key value (string)
  • ttl (optional) - Time-to-live in seconds (minimum 60)
  • expiration (optional) - Unix timestamp for absolute expiration
  • metadata (optional) - KV Native Metadata (max 1024 bytes)

Response:

{
  "success": true
}

Delete Key

DELETE /api/keys/:namespaceId/:keyName

Response:

{
  "success": true
}

Bulk Delete

POST /api/keys/:namespaceId/bulk-delete

Body:

{
  "keys": ["key1", "key2", "key3"]
}

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123",
    "status": "queued",
    "ws_url": "wss://..." 
  }
}

Note: Use polling endpoint /api/jobs/:jobId to track progress.

Bulk Copy

POST /api/keys/:namespaceId/bulk-copy

Body:

{
  "keys": ["key1", "key2"],
  "targetNamespaceId": "target_namespace_id"
}

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123",
    "status": "queued"
  }
}

Bulk TTL Update

POST /api/keys/:namespaceId/bulk-ttl

Body:

{
  "keys": ["key1", "key2"],
  "ttl": 3600
}

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123",
    "status": "queued"
  }
}

Metadata & Tags

Get Metadata and Tags

GET /api/metadata/:namespaceId/:keyName

Response:

{
  "success": true,
  "data": {
    "custom_metadata": {
      "email": "user@example.com",
      "extended_info": "..."
    },
    "tags": ["production", "active"]
  }
}

Update Metadata and Tags

PUT /api/metadata/:namespaceId/:keyName

Body:

{
  "custom_metadata": {
    "email": "user@example.com"
  },
  "tags": ["production", "active", "premium"]
}

Response:

{
  "success": true
}

Bulk Tag Operation

POST /api/metadata/:namespaceId/bulk-tag

Body:

{
  "keys": ["key1", "key2"],
  "tags": ["production", "v2"],
  "operation": "add"
}

Operations:

  • add - Add tags to existing tags
  • remove - Remove specified tags
  • replace - Replace all tags

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123",
    "status": "queued"
  }
}

Search

Search Keys

GET /api/search?query=user&namespaceId=...&tags=production,cache

Query Parameters:

  • query (optional) - Key name pattern (partial match)
  • namespaceId (optional) - Filter to specific namespace
  • tags (optional) - Comma-separated tags (all must match)

Response:

{
  "success": true,
  "data": [
    {
      "namespace_id": "...",
      "key_name": "user:123",
      "custom_metadata": {...},
      "tags": ["production", "active"]
    }
  ]
}

Note: Only searches keys with metadata in D1. External keys must be indexed first.

Import/Export

Export Namespace

GET /api/export/:namespaceId?format=json

Query Parameters:

  • format (optional) - json or ndjson (default: json)

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123",
    "status": "queued",
    "ws_url": "wss://..."
  }
}

Import to Namespace

POST /api/import/:namespaceId?collision=overwrite

Query Parameters:

  • collision (optional) - skip, overwrite, or fail (default: skip)

Body: JSON or NDJSON array of key objects

Example:

[
  {
    "name": "key1",
    "value": "value1",
    "ttl": 3600,
    "metadata": {"type": "example"},
    "custom_metadata": {"extended": "data"},
    "tags": ["production"]
  }
]

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123",
    "status": "queued"
  }
}

Get Job Status

GET /api/jobs/:jobId

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123",
    "status": "running",
    "operation_type": "export",
    "total_keys": 1000,
    "processed_keys": 500,
    "error_count": 0,
    "current_key": "user:500",
    "percentage": 50,
    "started_at": "2025-11-21T12:00:00.000Z",
    "completed_at": null
  }
}

Status Values:

  • queued - Job is queued
  • running - Job is in progress
  • completed - Job finished successfully
  • failed - Job failed with errors

Download Export

GET /api/jobs/:jobId/download

Response: File download (JSON or NDJSON)

R2 Backup & Restore

List R2 Backups

GET /api/r2-backup/:namespaceId/list

Response:

{
  "success": true,
  "data": [
    {
      "path": "backups/namespace123/1700000000000.json",
      "timestamp": 1700000000000,
      "size": 1048576,
      "uploaded": "2025-11-15T10:00:00.000Z"
    }
  ]
}

Backup to R2

POST /api/r2-backup/:namespaceId?format=json

Query Parameters:

  • format (optional) - json or ndjson (default: json)

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123",
    "status": "queued"
  }
}

Restore from R2

POST /api/r2-restore/:namespaceId

Body:

{
  "backupPath": "backups/namespace123/1700000000000.json"
}

Response:

{
  "success": true,
  "data": {
    "job_id": "job_abc123",
    "status": "queued"
  }
}

Note: Restore always overwrites existing keys.

Job History

List Jobs

GET /api/jobs?limit=50&offset=0&status=completed&operation_type=export

Query Parameters:

  • limit (optional) - Results per page (default: 50)
  • offset (optional) - Pagination offset (default: 0)
  • status (optional) - Filter by status
  • operation_type (optional) - Filter by operation type
  • namespace_id (optional) - Filter by namespace
  • start_date (optional) - Filter by start date (ISO timestamp)
  • end_date (optional) - Filter by end date (ISO timestamp)
  • job_id (optional) - Search by job ID (partial match)
  • min_errors (optional) - Filter jobs with error_count >= threshold
  • sort_by (optional) - Column to sort by (default: started_at)
  • sort_order (optional) - asc or desc (default: desc)

Response:

{
  "success": true,
  "data": {
    "jobs": [...],
    "total": 100,
    "limit": 50,
    "offset": 0
  }
}

Get Job Events

GET /api/jobs/:jobId/events

Response:

{
  "success": true,
  "data": [
    {
      "event_type": "started",
      "timestamp": "2025-11-21T12:00:00.000Z",
      "metadata": {}
    },
    {
      "event_type": "progress_25",
      "timestamp": "2025-11-21T12:05:00.000Z",
      "metadata": {
        "processed": 250,
        "total": 1000
      }
    }
  ]
}

Event Types:

  • started - Job started
  • progress_25 - 25% complete
  • progress_50 - 50% complete
  • progress_75 - 75% complete
  • completed - Job completed
  • failed - Job failed

Audit Logs

Get Namespace Audit Log

GET /api/audit/:namespaceId?limit=100&offset=0&operation=create

Query Parameters:

  • limit (optional) - Results per page (default: 100)
  • offset (optional) - Pagination offset (default: 0)
  • operation (optional) - Filter by operation type

Response:

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": 123,
        "namespace_id": "...",
        "key_name": "user:123",
        "operation": "create",
        "user_email": "user@example.com",
        "timestamp": "2025-11-21T12:00:00.000Z",
        "details": "Created key with TTL"
      }
    ],
    "total": 1000
  }
}

Get User Audit Log

GET /api/audit/user/:userEmail?limit=100&offset=0

Response: Same format as namespace audit log

Admin Utilities

Sync Keys to Search Index

POST /api/admin/sync-keys/:namespaceId

Indexes all keys in a namespace for search. Useful for keys created outside the UI.

Response:

{
  "success": true,
  "data": {
    "total_keys": 1000,
    "synced": 1000
  }
}

Backup & Restore (Single Version)

Create Backup

POST /api/backup/:namespaceId/:keyName/undo

Creates a backup of the current key value before modification.

Response:

{
  "success": true
}

Check Backup Exists

GET /api/backup/:namespaceId/:keyName/check

Response:

{
  "success": true,
  "data": {
    "exists": true,
    "timestamp": "2025-11-21T12:00:00.000Z"
  }
}

Rate Limits

  • Bulk Operations: Processed in batches of 10,000 keys
  • List Keys: Max 1000 keys per request
  • API Requests: Subject to Cloudflare Workers rate limits

Error Codes

Code Description
400 Bad Request - Invalid parameters
401 Unauthorized - Missing or invalid JWT
403 Forbidden - Access denied
404 Not Found - Resource doesn't exist
500 Internal Server Error - Worker error

Webhooks

Currently not supported. Use job polling for progress updates.

Next Steps

Home

Getting Started

User Documentation

Technical

Guides

Links

Clone this wiki locally