HTTP API: changes
The 1 operation tagged changes, each with its parameters, its body and what it answers.
What changed since you last looked
GET /v1/changes
Return what has happened, oldest first, that this caller is entitled to know about.
A period is ?created_at.gte=, and it is a different question from ?since=. A cursor
resumes where you left off and is inclusive-with-dedupe, so it is what a client that polls
should send; a period is a statement about a stretch of time and is not resumable. Somebody
asking what happened on a particular day has no cursor to offer, and a client polling has no
date in mind. Both are accepted and they compose.
Resuming is ?since=, not a cursor. Take the seq of the last event you dealt with
and send it back; you will receive it again and everything after it. has_more says
whether another page is waiting immediately — when it is false you are caught up, and
polling again will return only what happens next.
Going the other way is ?before=. With newest set, has_more means there are
earlier events, and since is a floor — so walking back through a long history is
?before=<the earliest seq you hold>, exclusive. Every answer still reads oldest first.
Ordered oldest first, because a feed is read forwards. The per-item histories run the other way, because "what happened to this" is a question about the recent past.
Parameters
since(integerornull, in query): Resume from this seq, inclusive. Send back the seq of the last event you processed; you will see it again and should ignore what you already have.before(integerornull, in query): Read only events earlier than this seq, exclusive. With 'newest' it is how you walk back through a long history: send the seq of the earliest event you already have. Composes with 'since', and together they are a range.workspace_id(stringornull, in query): Narrow to one workspace, by id or slug. The default spans all of them.actor(stringornull, in query): 'me' for what this credential itself did, or a username for everything that account did through any of its credentials. Omit for everything you can see.newest(boolean, in query): Start at the newest events rather than the oldest. For a first look at a long history; the page still reads forwards. Ignored when 'since' is given.limit(integerornull, in query): How many to return. At least 1; capped at the instance's max_page_size.format(stringornull, in query): 'full' (default), 'compact' for one aligned line per item, or 'ids' for the addresses alone. Compact is roughly a twentieth the size of full.fields(stringornull, in query): Comma-separated field names to return instead of the whole item, e.g. 'ref,title,due_at'. GET /v1/meta lists what each entity has. Cannot be combined with 'format'.
Responses
200:Changes. Successful Response422:HTTPValidationError. Validation Error