NLS API Documentation

The NLS API provides a simple key-value storage interface, similar to localStorage but persistent and accessible from any device or platform. All endpoints return JSON responses.

Base URL: https://notlocalstorage.io/api/v1/storage

Authentication

All API requests require authentication via two headers: X-API-Key (your organization's API key) and X-App-Key (your application's key). You can find both keys in the dashboard.

const response = await fetch('https://notlocalstorage.io/api/v1/storage/my-key', {
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'X-App-Key': 'YOUR_APP_KEY'
  }
});
// React hook for NLS
import { useState, useEffect } from 'react';

function useNLS(key) {
  const [value, setValue] = useState(null);

  useEffect(() => {
    fetch(`https://notlocalstorage.io/api/v1/storage/${key}`, {
      headers: { 'X-API-Key': 'YOUR_API_KEY', 'X-App-Key': 'YOUR_APP_KEY' }
    }).then(r => r.json()).then(d => setValue(d.value));
  }, [key]);

  return value;
}
<!-- Vue composable for NLS -->
import { ref, onMounted } from 'vue';

export function useNLS(key) {
  const value = ref(null);

  onMounted(async () => {
    const res = await fetch(`https://notlocalstorage.io/api/v1/storage/${key}`, {
      headers: { 'X-API-Key': 'YOUR_API_KEY', 'X-App-Key': 'YOUR_APP_KEY' }
    });
    value.value = (await res.json()).value;
  });

  return value;
}
<!-- Svelte store for NLS -->
import { writable } from 'svelte/store';

export function nlsStore(key) {
  const store = writable(null);

  fetch(`https://notlocalstorage.io/api/v1/storage/${key}`, {
    headers: { 'X-API-Key': 'YOUR_API_KEY', 'X-App-Key': 'YOUR_APP_KEY' }
  }).then(r => r.json()).then(d => store.set(d.value));

  return store;
}
curl https://notlocalstorage.io/api/v1/storage/my-key \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-App-Key: YOUR_APP_KEY"

Rate Limits

API requests are rate-limited per application key:

Plan Read Operations Write Operations
Free 60 requests/minute 30 requests/minute
Team 300 requests/minute 150 requests/minute
Enterprise Custom Custom

Rate limit headers are included in all responses:

Error Handling

The API uses standard HTTP status codes:

Code Meaning
200 Success
201 Created
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
402 Payment Required - Storage limit exceeded
404 Not Found - Key does not exist
429 Too Many Requests - Rate limit exceeded
500 Server Error

Error responses include a JSON body:

{ "error": "Key not found", "key": "my-key" }

Get Item

GET /api/v1/storage/{key}

Retrieve a stored value by its key.

Parameters

Name Type Description
key string The key to retrieve required

Response

{ "key": "user:preferences", "value": { "theme": "dark", "language": "en" }, "size": 42, "updated_at": "2024-01-15T10:30:00Z" }

Examples

const response = await fetch('https://notlocalstorage.io/api/v1/storage/user:preferences', {
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'X-App-Key': 'YOUR_APP_KEY' }
});
const data = await response.json();
console.log(data.value); // { theme: 'dark', language: 'en' }
import { useState, useEffect } from 'react';

function UserPreferences() {
  const [prefs, setPrefs] = useState(null);

  useEffect(() => {
    fetch('https://notlocalstorage.io/api/v1/storage/user:preferences', {
      headers: { 'X-API-Key': 'YOUR_API_KEY', 'X-App-Key': 'YOUR_APP_KEY' }
    }).then(r => r.json()).then(d => setPrefs(d.value));
  }, []);

  return <div>Theme: {prefs?.theme}</div>;
}
<script setup>
import { ref, onMounted } from 'vue';

const prefs = ref(null);

onMounted(async () => {
  const res = await fetch('https://notlocalstorage.io/api/v1/storage/user:preferences', {
    headers: { 'X-API-Key': 'YOUR_API_KEY', 'X-App-Key': 'YOUR_APP_KEY' }
  });
  prefs.value = (await res.json()).value;
});
</script>

<template>Theme: {{ prefs?.theme }}</template>
<script>
import { onMount } from 'svelte';

let prefs = null;

onMount(async () => {
  const res = await fetch('https://notlocalstorage.io/api/v1/storage/user:preferences', {
    headers: { 'X-API-Key': 'YOUR_API_KEY', 'X-App-Key': 'YOUR_APP_KEY' }
  });
  prefs = (await res.json()).value;
});
</script>

<p>Theme: {prefs?.theme}</p>
curl https://notlocalstorage.io/api/v1/storage/user:preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-App-Key: YOUR_APP_KEY"

Set Item

POST /api/v1/storage

Store a new key-value pair. If the key already exists, it will be overwritten.

Request Body

Name Type Description
key string The key to store (max 255 chars) required
value any The value to store (JSON serializable) required

Response

{ "success": true, "key": "user:preferences", "size": 42, "created_at": "2024-01-15T10:30:00Z" }

Examples

const response = await fetch('https://notlocalstorage.io/api/v1/storage', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'X-App-Key': 'YOUR_APP_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    key: 'user:preferences',
    value: { theme: 'dark' }
  })
});
function SavePreferences() {
  const savePrefs = async (prefs) => {
    await fetch('https://notlocalstorage.io/api/v1/storage', {
      method: 'POST',
      headers: {
        'X-API-Key': 'YOUR_API_KEY',
        'X-App-Key': 'YOUR_APP_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        key: 'user:preferences',
        value: prefs
      })
    });
  };

  return <button onClick={() => savePrefs({ theme: 'dark' })}>Save</button>;
}
<script setup>
async function savePrefs(prefs) {
  await fetch('https://notlocalstorage.io/api/v1/storage', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'X-App-Key': 'YOUR_APP_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ key: 'user:preferences', value: prefs })
  });
}
</script>

<template>
  <button @click="savePrefs({ theme: 'dark' })">Save</button>
</template>
<script>
async function savePrefs(prefs) {
  await fetch('https://notlocalstorage.io/api/v1/storage', {
    method: 'POST',
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'X-App-Key': 'YOUR_APP_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ key: 'user:preferences', value: prefs })
  });
}
</script>

<button on:click={() => savePrefs({ theme: 'dark' })}>Save</button>
curl -X POST https://notlocalstorage.io/api/v1/storage \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "user:preferences", "value": {"theme": "dark"}}'

Update Item

PUT /api/v1/storage/{key}

Update an existing key's value. Returns 404 if the key doesn't exist.

Request Body

Name Type Description
value any The new value required

Examples

await fetch('https://notlocalstorage.io/api/v1/storage/user:preferences', {
  method: 'PUT',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'X-App-Key': 'YOUR_APP_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ value: { theme: 'light' } })
});
curl -X PUT https://notlocalstorage.io/api/v1/storage/user:preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-App-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": {"theme": "light"}}'

Delete Item

DELETE /api/v1/storage/{key}

Delete a stored key-value pair.

Examples

await fetch('https://notlocalstorage.io/api/v1/storage/user:preferences', {
  method: 'DELETE',
  headers: { 'X-API-Key': 'YOUR_API_KEY', 'X-App-Key': 'YOUR_APP_KEY' }
});
curl -X DELETE https://notlocalstorage.io/api/v1/storage/user:preferences \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-App-Key: YOUR_APP_KEY"

List Items

GET /api/v1/storage

List all stored items with optional pagination and search.

Query Parameters

Name Type Description
search string Filter keys containing this string
page integer Page number (default: 1)
per_page integer Items per page (default: 50, max: 100)

Response

{ "data": [ { "key": "user:1", "size": 128, "updated_at": "2024-01-15T10:30:00Z" }, { "key": "user:2", "size": 256, "updated_at": "2024-01-15T11:00:00Z" } ], "meta": { "current_page": 1, "total": 42, "per_page": 50 } }

Clear All

DELETE /api/v1/storage

Delete all stored items for this application. Use with caution!

Examples

curl -X DELETE https://notlocalstorage.io/api/v1/storage \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-App-Key: YOUR_APP_KEY"

Batch Operations

POST /api/v1/storage/batch

Set multiple key-value pairs in a single request (max 100 items).

Request Body

{ "items": [ { "key": "user:1", "value": { "name": "Alice" } }, { "key": "user:2", "value": { "name": "Bob" } } ] }

Batch Get

POST /api/v1/storage/batch/get

Get multiple values in a single request.

// Request { "keys": ["user:1", "user:2", "user:3"] } // Response { "items": { "user:1": { "name": "Alice" }, "user:2": { "name": "Bob" }, "user:3": null } }

Stats

GET /api/v1/storage/stats

Get storage usage statistics for your application.

Response

{ "items_count": 1542, "total_size": 524288, "total_size_formatted": "512 KB", "storage_limit": 104857600, "storage_limit_formatted": "100 MB", "usage_percent": 0.5 }

JavaScript SDK

A lightweight wrapper for browser and Node.js environments.

Installation

npm install @notlocalstorage/sdk
<script src="https://cdn.notlocalstorage.io/sdk.min.js"></script>

Usage

import { NLS } from '@notlocalstorage/sdk';

const nls = new NLS({ appKey: 'YOUR_APP_KEY' });

// Set a value
await nls.set('user:prefs', { theme: 'dark' });

// Get a value
const prefs = await nls.get('user:prefs');

// Delete a value
await nls.delete('user:prefs');
import { useNLS } from '@notlocalstorage/react';

function Settings() {
  const [prefs, setPrefs] = useNLS('user:prefs');

  return (
    <button onClick={() => setPrefs({ theme: 'dark' })}>
      Dark Mode
    </button>
  );
}
<script setup>
import { useNLS } from '@notlocalstorage/vue';

const { value: prefs, set } = useNLS('user:prefs');
</script>

<template>
  <button @click="set({ theme: 'dark' })">Dark Mode</button>
</template>

React SDK

React hooks for seamless NLS integration with automatic state management.

Installation

npm install @notlocalstorage/react

Setup

// App.jsx - Wrap your app with the provider
import { NLSProvider } from '@notlocalstorage/react';

function App() {
  return (
    <NLSProvider appKey="YOUR_APP_KEY">
      <YourApp />
    </NLSProvider>
  );
}

Hooks

import { useNLS, useNLSValue } from '@notlocalstorage/react';

// Full control with get/set
function Settings() {
  const [prefs, setPrefs, { loading, error }] = useNLS('user:prefs');

  if (loading) return <span>Loading...</span>;

  return (
    <div>
      <p>Theme: {prefs?.theme}</p>
      <button onClick={() => setPrefs({ theme: 'dark' })}>
        Dark Mode
      </button>
    </div>
  );
}

// Read-only value
function DisplayTheme() {
  const prefs = useNLSValue('user:prefs');
  return <span>{prefs?.theme}</span>;
}

With TypeScript

interface UserPrefs {
  theme: 'light' | 'dark';
  language: string;
}

const [prefs, setPrefs] = useNLS<UserPrefs>('user:prefs');

Vue SDK

Vue 3 composables for reactive NLS integration.

Installation

npm install @notlocalstorage/vue

Setup

// main.js - Install the plugin
import { createApp } from 'vue';
import { nlsPlugin } from '@notlocalstorage/vue';

const app = createApp(App);
app.use(nlsPlugin, { appKey: 'YOUR_APP_KEY' });
app.mount('#app');

Composables

<script setup>
import { useNLS } from '@notlocalstorage/vue';

// Reactive value with get/set
const { value: prefs, set, loading, error } = useNLS('user:prefs');

function setDarkMode() {
  set({ theme: 'dark' });
}
</script>

<template>
  <div v-if="loading">Loading...</div>
  <div v-else>
    <p>Theme: {{ prefs?.theme }}</p>
    <button @click="setDarkMode">Dark Mode</button>
  </div>
</template>

With TypeScript

interface UserPrefs {
  theme: 'light' | 'dark';
  language: string;
}

const { value, set } = useNLS<UserPrefs>('user:prefs');

Svelte SDK

Svelte stores for reactive NLS integration.

Installation

npm install @notlocalstorage/svelte

Setup

// nls.js - Create your NLS instance
import { createNLS } from '@notlocalstorage/svelte';

export const nls = createNLS({
  appKey: 'YOUR_APP_KEY'
});

Stores

<script>
import { nls } from './nls.js';

// Create a reactive store for a key
const prefs = nls.store('user:prefs');

function setDarkMode() {
  prefs.set({ theme: 'dark' });
}
</script>

{#if $prefs.loading}
  <p>Loading...</p>
{:else}
  <p>Theme: {$prefs.value?.theme}</p>
  <button on:click={setDarkMode}>Dark Mode</button>
{/if}

Direct API Access

<script>
import { nls } from './nls.js';

// Direct get/set without stores
async function loadPrefs() {
  const prefs = await nls.get('user:prefs');
  console.log(prefs);
}

async function savePrefs() {
  await nls.set('user:prefs', { theme: 'dark' });
}
</script>