The HTTP API.

What it is for

The app on a device reads its data with Arda.db.dataset() and sends new records up with Arda.db.push(). ArdaForm keeps every device's copy in step. The HTTP API is the other side of that: what your systems write, the devices sync; what the devices push, your systems read.

• Publish a price list, a member list or a menu to every device — or only to the devices of one site.
• Collect what the devices recorded: check-ins, sales, readings, form answers.
• Upload the images and videos an app shows; devices download them by themselves.
• Set up the webhooks your app calls, and read their delivery log.

1 · Get a key

Keys are made in the portal, on a project's API keys tab. A key belongs to that one project, so no call ever needs a project id — the key already says which project it is for.

• Keys start with af_. The whole key is shown once, when you make it — copy it then. After that the portal only shows its first few characters.
• Choose what the key may do: read, change, add or delete, area by area — and for records, down to single datasets. A key that only reads a catalogue cannot change it.
• Give it an expiry date if you like. A key stops working at the end of that day.
• Every plan includes API access — the free plan with one key and a lower request rate. Your app's manifest.json can also limit what the API may do with each dataset: "api": "rw", "ro" or "none".

The portal guide shows both screens.

2 · Your first call

Every request carries the key in an Authorization header. This one asks the API to confirm the key works:

$ curl -H "Authorization: Bearer af_…your key…" https://api.ardaform.net/v1/auth

The answer names the key, its project, your account and your limits — how many datasets, how much storage, how many calls a minute. Read it once when your program starts, and you will never have to find a limit by hitting it.

3 · Send some records

Records are plain JSON objects, and what is in them is up to you. Give each one an id and sending it again updates it rather than adding a copy. This adds or updates two members of the members dataset:

$ curl -X POST -H "Authorization: Bearer $ARDA_KEY" -H "Content-Type: application/json" \
    -d '[{"id": "1042", "name": "Sam Patel", "site": "northgate-01"},
         {"id": "1043", "name": "Ana Silva", "site": "northgate-01"}]' \
    https://api.ardaform.net/v1/datasets/members/records

The devices pick them up by themselves. If the dataset is split by site, only the devices set to northgate-01 receive these two.

What you can reach

A webhook with no address is handy on its own: every call the app makes is simply kept, and your system reads them through the API whenever it likes — no public server of yours needed.

Good to know

• Errors always look the same — {"error": {"code": "…", "message": "…"}}. Check the code; the message is for people and may be reworded.
• Your plan sets how many calls a minute you get. Every answer says how many are left (X-RateLimit-Remaining). If you go over, you get a 429 with a Retry-After saying how many seconds to wait.
• Nothing is cached and nothing is allowed from another website: call it from a server or a script, where the key stays secret.
• v1 stays as it is. A change that would break your code arrives as v2 beside it, never as a surprise in v1.

The full description

The API describes itself, live, with no key needed:

https://api.ardaform.net/v1/openapi.json

It lists every endpoint with its parameters, bodies and error codes. Paste the link into Postman (Import → Link), Insomnia, Bruno, Hoppscotch or Swagger UI and every call is ready to try. Import from the link rather than saving a copy — the link is always current. https://api.ardaform.net/v1 also lists every endpoint in one short answer.

A full written reference — every field and every refusal, in plain words — is being finished. Until it is published, the description above is the complete and exact one, and it is what the API itself answers to.

Open openapi.json ↗