Api Reference
This reference only covers read operations. Please refer to the Quick Guide to Codecks API for information about write operations.
Basics
simple syntax example:
{
"_root": [{
"relname($query)": [...fields and relations],
"relname($query2)": [...fields and relations],
}]
}
curl example:
curl 'https://api.codecks.io/' \
-H 'X-Account: [SUBDOMAIN]' \
-H 'Content-Type: application/json' \
-H 'X-Auth-Token: [TOKEN]' \
--data-binary '{"query":{"_root":[{"account":["name"]}]}}'
The Token corresponds to the value of the at
cookie sent to api.codecks.io
requests. A feature for dedicated API-Tokens is planned.
relname($query)
here’s the syntax for what a $query
looks like.
{fieldName1: $val, fieldName2: {"op": $op, "value": $val}}
Note that {fieldName1: $val}
is a shortcut for {fieldName1: {"op": "eq", "value": $val}}
The $query
portion needs to be sent to JSON.stringify()
or similar. For readiablity’s sake we display the non-stringified versions here.
If you want to fetch all related items you can leave out the $query
portion like this:
...
"deck": [{
"cards": [...fields and relations],
}]
...
Possible values for $op
eq
: value | nullneq
: value | nullin
: arraynotIn
: arraygt
: ordinal valuegte
: ordinal valuelt
: ordinal valuelte
: ordinal valueinOrNull
: arraycontains
: string (if field is of type string)has
: value (if field is of type array)overlaps
: array (if field is of type array)search
: string if field is searchable (so far only available for thecontent
field within thecard
model)
Filtering by values of relation fields
fieldName
can also be used to access a relation’s properties. For a card
this could be e.g {resolvables: {context: ["block", "review"], isClosed: false}}
.
This would fetch all cards that have at least one non-closed resolvable with the block
orreview
context
Negation:
you can also do {!resolvables: {context: ["block", "review"], isClosed: false}}
to say only show cards with no such resolvables.
“in” - shortcut
relname({"projectId": [123, 234]})
is equivalent to
relname({"projectId": {"op": "in", value: [123, 234]}})
special fields
-
$or
combines multiple queries viaor
, sub queries may not contain special fields (beside more $or and $and)relname({"$or": [{"isArchived": true}, {"status": "done"}]})
-
$and
combines multiple queries viaand
, sub queries may not contain special fields (beside more $or and $and)relname({"$and": [ {"effort": {"op": "gt", value: 0}}, {"effort": {"op": "lte", value: 5}} ]})
-
$order
: OrderExpressionrelname({"deckId": 123, "$order": "createdAt"})
Full OrderExpression is
{"field": fieldName, "dir": "desc"|"asc"}[]
Shortcuts are
{"field": fieldName, "dir": "desc"|"asc"}
-> [{"field": fieldName, "dir": "desc"|"asc"}
]fieldName
-> [{"field": fieldName, "dir": "asc"}
]-fieldName
-> [{"field": fieldName, "dir": "desc"}
]
-
$first
: trueonly works when order is provided, return singleton
relname({"deckId": 123, "$order": "createdAt", "$first": true})
-
$limit
: numberonly works when order is provided, there’s always a maximum $limit of 3000
relname({"deckId": 123, "$order": "createdAt", "$limit": 10})
-
$offset
: numberonly works when limit (and thus order) is provided
relname({"deckId": 123, "$order": "createdAt", "$limit": 10, "$offset": 20})
root level id-based queries
root level queries look like this:
{
"modelname($id)": [...fields and relations]
}
$id
is either a string for single id models or a JSON array for compound ids.
The API Reference
Below is a raw output of all available models, their fields and relations.
Note that this information should not be considered stable. While most properties haven’t changed in years, there’s no guarantee they won’t change in the future.