Skip to content

Getting started

The idea is to be able to quickly store and retrieve data with minimum fuss. With that goal in mind, the API was designed to be as frictionless as possible. Basically obtain an API key and use read and write endpoint with that key. No logins, no sign ups - just you and your data that will delete itself when you forget about it.

Step 1: Get Your API key.

/getkey endpoint takes two parameters:

  1. the key-name (a.k.a. key id) and
  2. a seed phrase.

A new API key will be generated if one does not exist for the supplied "key_id / seed" pair.

You are now ready to write and read "key"={value} pairs via HTTP GET and HTTP POST requests.

> curl https://prefs/us/getkey?user=[key_id]&seed=[seed_phrase]

<script src="https://prefs.us/prefs.us.min.js"></script>

prefs_us.getkey("key_id", "seed_phrase", (reply)=>{
  console.log("API key: %s", reply.token);
});

See also: Generate API Key ahead of time

Step 2: API Endpoints

Use /read and /write endpoints to save and retrieve your data.

To save data:

> curl https://prefs.us/write?key=[apikey]&...

<script src="https://prefs.us/prefs.us.min.js"></script>

prefs_us.using("[api_key"]).write("dataKey=dataValue");

To read data:

> curl https://prefs.us/read?key=[apikey]

<script src="https://prefs.us/prefs.us.min.js"></script>

prefs_us.read("dataKey");

https://prefs.us/read?key=[apikey]&...

Quick notes

  1. Each endpoint requires that you supply a &key=[api-key] parameter with every request.

  2. Keep and use the same key for all subsequent queries to keep your items grouped together, whether saving or retrieving them.

  3. Use grouping parameters such as 'project', 'domain', 'subdomain', or 'list' to help with organizing your data attached to your API key.

  4. Create as many keys as you need but traffic may be a subject to rate limiting.

  5. All timestamps are UTC