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 | null
• neq: value | null
• in: array
• notIn: array
• gt: ordinal value
• gte: ordinal value
• lt: ordinal value
• lte: ordinal value
• inOrNull: array
• contains: 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 the content field within the card 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 blockorreview 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 via or, sub queries may not contain special fields (beside more $or and $and)

  relname({"$or": [{"isArchived": true}, {"status": "done"}]})

• $and combines multiple queries via and, 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: OrderExpression

  relname({"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: true

  only works when order is provided, return singleton

  relname({"deckId": 123, "$order": "createdAt", "$first": true})

• $limit: number

  only works when order is provided, there’s always a maximum $limit of 3000

  relname({"deckId": 123, "$order": "createdAt", "$limit": 10})

• $offset: number

  only 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.