ReSync API v1

ReSync is a shared record of things and what has happened to them. This page explains the five ideas you need before the first call. Everything else in this pack builds on them.

The current version of this pack is published at docs.limnal.dev.

Resources

Everything in ReSync is a resource: a customer, a bid, a cabinet, a machine, a person, a company. A resource has an id, a name, an optional identifier of your own choosing, and a bag of properties — free-form key/value data.

Resource ids are integers, but the API returns them as strings. Some are larger than a JavaScript number can hold exactly. Keep them as strings and you will never have to think about it again.

Types

Every resource has one type, and a type is named by a short stable code — cab_bid, cab_customer, cab_cat_wall. The code is the thing you write in your own source; it never changes. Names and display labels do change, so do not key on them.

Types form a tree. Asking for a type in a list also returns resources of the types beneath it.

Ownership

Every resource is owned by one organization. Ownership is not a permission setting you can adjust per request — it is a fact about the resource, and it is the boundary your key works inside.

The ledger

ReSync does not overwrite history. Every change appends an event: what happened, to which resource, when, who did it, and which system wrote it. Reading a resource shows you the current state; reading its events shows you how it got there, including the changes you made.

You do not write events directly. You call an ordinary endpoint and the event is recorded for you.

What your key is

Your key is a credential owned by one organization. That single fact decides what it can do:

• It is bound to that organization's resources. A resource owned by anyone else is not visible to it, by id or any other route. There is no "public" resource and no cross-organization read.
• It carries a read set, an operate set and a find-or-create set, each a list of type codes.
  • Read set — the types you may list and fetch.
  • Operate set — the types you may change. Operating implies reading, so a type in the operate set does not need to be repeated in the read set.
  • Find-or-create set — the types you may bring into existence, by your own identifier. Being able to change a type is not the same as being able to create one, so this list is separate.
• A type in none of the sets does not exist as far as your key is concerned.

You cannot change your own scopes. An administrator at the owning organization changes them, and every change is recorded on the ledger.

Call GET /v1/api-keys/self to see exactly what your key holds. That is the first call in the quickstart, and it is worth making it the first call your integration makes too.

Next: quickstart.md — one whole bid, from an empty start to a converted order, with a real response for every door.