API
Read your own recipes, batches, stock and products from a shop, a spreadsheet or a script. Version 1 reads and never writes.
A key
Make one on your account page, under API keys. It is part of the Business plan. The key is shown once, when you make it; we keep only a scramble of it, so a lost key is revoked and replaced, not recovered. Anyone holding a key can read your account's records, so keep it on a server, not in a page other people load.
Sending it
With every request, in the Authorization header:
curl -H "Authorization: Bearer sf_your_key" https://soapformulator.com/api/v1/recipesAnswers are JSON. Dates are ISO 8601 in UTC. Any site may call the API from a browser (CORS is open), because the key is the whole credential and no cookie is read.
Addresses
| GET | Answers with |
|---|---|
| /api/v1/recipes | Your saved recipes: id, name, version, superfatPercent, lye, totalOilGrams, createdAt, updatedAt, url. Newest change first, up to 500. |
| /api/v1/recipes/{id} | One recipe with its document: the oils, lye, superfat, water, fragrance and additives exactly as saved. Numbers such as the lye weight are not stored: work them out, or open the url. |
| /api/v1/batches | Your batches: id, code, recipeId, recipeVersion, madeAt, createdAt, updatedAt. Newest first, up to 500. |
| /api/v1/batches/{id} | One batch with its document: the weights, temperatures, notes, outcomes, cure weigh-ins and the recipe snapshot it was made from. |
| /api/v1/stock | Your stock items: id, name, kind, ingredient, unit, onHand, averageCost, reorderAt, supplier, archived, updatedAt. |
| /api/v1/products | Your products: id, name, sku, createdAt, updatedAt and the product document (price, barcode, packaging, label text). |
When something is refused
The answer has an error code that stays the same and a message in English that may change.
| 401 unauthorized | No key, a key in the wrong form, or a revoked key. |
| 402 plan_required | The account the key belongs to is not on Business. |
| 404 not_found | No such address, or nothing with that id on this account. |
| 405 method_not_allowed | Anything but GET. The API reads; it never changes anything. |
| 429 rate_limited | More than 600 requests in an hour, for this key. |
Changes
Fields may be added to version 1. None will be removed or change meaning; that would be version 2, at a new address, with version 1 kept running.