# JsonStorage API for Autonomous Agents & LLMs

> High-performance JSON key-value & blob storage at the Edge for AI agents, LLM memory, scrapers, and dynamic configs.
> Deployed on Cloudflare Workers & R2 Storage.

## Overview
JsonStorage provides persistent, low-latency JSON storage. Autonomous AI agents can self-provision, store memory or app data, and manage billing programmatically.

## Paid-Only Bot Model
To ensure service quality and prevent spam, bot access is strictly paid-only with an optional 7-day Stripe trial.
- **Basic Plan**: $1/month (100 items, up to 50KB/item, 1,000 req/day)
- **Essential Plan**: $9/month (500 items, up to 100KB/item, 10,000 req/day)
- **Pro Plan**: $29/month (2,500 items, up to 1MB/item, 50,000 req/day)

---

## 1. Automated Bot Registration & Stripe Checkout

### Endpoint: `POST https://api.jsonstorage.net/v1/auth/bot/signup`
Use this endpoint to provision a bot account and obtain credentials.

#### Request Body
```json
{
  "name": "My-Research-Agent",
  "owner_email": "developer@example.com",
  "plan": "basic",
  "trial": true
}
```
- `name` (string, required): Name of the bot or agent.
- `owner_email` (string, required): Developer or company email for billing & invoices.
- `plan` (string, optional): `"basic"` ($1/mo), `"essential"` ($9/mo), or `"pro"` ($29/mo). Default: `"basic"`.
- `trial` (boolean, optional): Default `true` (enables 7-day free trial on Stripe).

#### Response (HTTP 201 Created)
```json
{
  "success": true,
  "status": "pending_payment",
  "userId": "d7b928f1-4321-...",
  "apiKey": "4f92bc80-1234-...",
  "plan": "Basic",
  "trialDays": 7,
  "checkoutUrl": "https://api.jsonstorage.net/v1/billing/pay/cs_...",
  "sessionId": "cs_...",
  "instructions": "This API key requires an active paid subscription or trial. Open checkoutUrl to authorize payment with Stripe.",
  "endpoints": {
    "status": "https://api.jsonstorage.net/v1/auth/bot/status?apiKey=...",
    "store": "POST https://api.jsonstorage.net/v1/json",
    "get": "GET https://api.jsonstorage.net/v1/json/{userId}/{itemId}?apiKey=..."
  }
}
```

---

## 2. Autonomous Direct Payments (Machine-to-Machine)

For agents with virtual card access or pre-authorized payment methods (e.g. via Stripe Agent Toolkit or Stripe Issuing):

### Endpoint: `POST https://api.jsonstorage.net/v1/auth/bot/subscribe`
```json
{
  "name": "Trading-Agent",
  "owner_email": "finance@fund.com",
  "plan": "pro",
  "payment_method_id": "pm_card_visa"
}
```
Directly activates the bot and API key immediately without human redirection.

---

## 3. Core Storage Operations

Once activated, include your API key via `apiKey` query param or `x-api-key` header:

### Store JSON Blob
```http
POST https://api.jsonstorage.net/v1/json
Content-Type: application/json
x-api-key: {apiKey}

{
  "state": "running",
  "checkpoint": 42,
  "data": { "key": "value" }
}
```

### Retrieve JSON Blob
```http
GET https://api.jsonstorage.net/v1/json/{userId}/{itemId}?apiKey={apiKey}
```

### Update JSON Blob (Replace)
```http
PUT https://api.jsonstorage.net/v1/json/{userId}/{itemId}?apiKey={apiKey}
Content-Type: application/json

{ "state": "completed", "result": 100 }
```

### Deep Merge JSON (Patch)
```http
PATCH https://api.jsonstorage.net/v1/json/{userId}/{itemId}?apiKey={apiKey}
Content-Type: application/json

{ "checkpoint": 43 }
```

### Check Bot & Plan Status
```http
GET https://api.jsonstorage.net/v1/auth/bot/status?apiKey={apiKey}
```