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.

_root

Relations

releases
release[]
accountOnboardingSteps
accountOnboardingStep[]
account
account
loggedInUser
user
cardsStatusHistory
cardsStatusHistory[]
cardsEffortHistory
cardsEffortHistory[]
cardsFinishedHistory
cardsFinishedHistory[]
cardsTimeToFinished
cardsTimeToFinished[]

accountOnboardingStep

Fields

chapter
string
description
string
milestone
string
sortValue
string
title
string
variants
array
xp
int

accountOnboarding

Fields

account
account
steps
json
variants
array

accountRole

Fields

account
account
createdAt
date
isBillingContact
string
lastChangedAt
date
role
string
roleAsPrio
int
user
user

accountUserAchievement

Fields

account
account
context
json
user
user
value
json

accountUserSetting

Fields

account
account
inboxDeck
deck
timelineScaleTypeOverwrite
unknown
user
user
wantsWeeklyDigestMail
bool

account

Fields

activeFeatureFlags
json
activeProjectCount
int
allowInheritHeroCover
bool
attachmentCoverMode
string
billingCity
string
billingCountryCode
string
billingLine1
string
billingLine2
string
billingName
string
billingType
string
billingZip
string
coupon
json
createdAt
date
dependenciesEnabled
bool
disabledAt
date
disabledBy
user
effortScale
json
fallbackEffort
int
hideCompletedCardCountForDecks
bool
isDisabled
bool
isLearning
bool
isNonProfit
bool
maxHandSlotCount
int
maxTimeTrackingSegmentMsDuration
int
milestonesEnabled
bool
name
string
netGiftAmount
int
offeringTrial
bool
persona
string
priorityLabels
json
seats
int
sprintsEnabled
bool
staffPermission
string
statusChangeDurations
json
subdomain
string
timeTrackingMode
string
timeTrackingSwimLaneInfo
bool
timelineScaleType
string
totalMediaByteUsage
bigint
workdays
json
workflowMode
string

Relations

cards
card[]
invoices
invoice[]
cardPresets
cardPreset[]
attachments
attachment[]
discordGuilds
discordGuild[]
timeTrackingSegments
timeTrackingSegment[]
workflowItems
workflowItem[]
deckAssignments
deckAssignment[]
assigneeAssignments
assigneeAssignment[]
assigneeDeckAssignments
assigneeDeckAssignment[]
wizards
wizard[]
milestones
milestone[]
sprints
sprint[]
sprintConfigs
sprintConfig[]
handCards
handCard[]
resolvables
resolvable[]
cardUpvotes
cardUpvote[]
resolvableParticipants
resolvableParticipant[]
userReportSettings
userReportSetting[]
cardOrders
cardOrder[]
accountUserAchievements
accountUserAchievement[]
userInviteCodes
userInviteCode[]
visionBoards
visionBoard[]
deckSubscriptions
deckSubscription[]
decks
deck[]
queueEntries
queueEntry[]
anyDecks
deck[]
projects
project[]
archivedProjects
project[]
anyProjects
project[]
invitations
userInvitation[]
githubIntegration
integration
slackIntegration
integration
affiliateCodes
affiliateCode[]
activities
activity[]
stripeAccountSync
stripeAccountSync
accountOnboarding
accountOnboarding

activeTimeTracker

Fields

account
account
card
card
createdAt
date
user
user

activity

Fields

card
card
changer
user
createdAt
date
data
json
deck
deck
isRemovedFromDeckEntry
bool
isRemovedFromMilestoneEntry
bool
isRemovedFromSprintEntry
bool
milestone
milestone
project
project
sprint
sprint
type
string

affiliateCodeStat

Fields

affiliateCode
affiliateCode
month
int
newVisitors
int
revenue
int
signups
int
visits
int
year
int

affiliateCode

Fields

account
account
code
string
createdAt
date
creator
user
isDeleted
bool
isDisabled
bool
label
string
message
string
remainingRedemptions
int
reward
json
validUntil
unknown
vanityUrl
string

Relations

assigneeAssignment

Fields

account
account
assignedBy
user
assignee
user
lastAssignedAt
date

assigneeDeckAssignment

Fields

account
account
assignedBy
user
assignee
user
deck
deck
lastAssignedAt
date

attachment

Fields

account
account
card
card
content
string
createdAt
date
creator
user
file
file
title
string

cardDiffNotification

Fields

account
account
asOwner
bool
card
card
changers
array
changes
json
createdAt
date
lastUpdatedAt
date
user
user

cardHistory

Fields

account
account
card
card
changer
user
diff
json
version
int
versionCreatedAt
date

cardOrderInDeck

Fields

card
card
changer
user
deck
deck
sortIndex
string

cardOrder

Fields

account
account
card
card
label
string
sortValue
string

cardPreset

Fields

account
account
createdAt
date
creator
user
data
json
name
string

cardSubscription

Fields

account
account
card
card
createdAt
date
user
user

cardUpvote

Fields

account
account
card
card
createdAt
date
discordUserInfo
json
type
string
user
user

card

Fields

account
account
accountSeq
int
assignee
user
checkboxInfo
array
checkboxStats
json
childCardInfo
string
content
string
coverFile
file
createdAt
date
creator
user
deck
deck
discordGuild
discordGuild
dueDate
day
effort
int
embeds
json
hasBlockingDeps
bool
isDoc
bool
isPublic
bool
lastUpdatedAt
date
legacyProject
project
legacyProjectSeq
int
masterTags
array
mentionedUsers
array
meta
json
milestone
milestone
parentCard
card
priority
unknown
sourceWorkflowItem
workflowItem
sprint
sprint
status
string
tags
array
title
string
version
int
visibility
string

Relations

resolvables
resolvable[]
handCards
handCard[]
timeTrackingSegments
timeTrackingSegment[]
cardSubscriptions
cardSubscription[]
cardOrders
cardOrder[]
resolvableEntries
resolvableEntry[]
attachments
attachment[]
totalTimeTrackingSums
timeTrackingSum
userTimeTrackingSums
timeTrackingSum[]
childCards
card[]
inDeps
card[]
outDeps
card[]
cardReferences
card[]

cardsEffortHistory

Fields

cardCount
bigint
date
day
effortSum
bigint

cardsFinishedHistory

Fields

assignee
user
cardCount
bigint
date
day
effortSum
bigint

cardsStatusHistory

Fields

count
int
date
day
status
string

cardsTimeToFinished

Fields

assignee
user
card
card
doneAt
date
effort
int
startedAt
date

dailyDiscordGuildVoteMembership

Fields

discordGuild
discordGuild
membershipCount
int
t
date

dailyPublicProjectMembership

Fields

membershipCount
int
project
project
t
date

publicProjectVisit

Fields

project
project
t
date
topReferrers
json
visitCounts
int

deckAssignment

Fields

account
account
deck
deck
lastAssignedAt
date
user
user

deckGuardian

Fields

account
account
deck
deck
user
user

deckSubscription

Fields

account
account
deck
deck
user
user

deck

Fields

account
account
accountSeq
int
content
string
coverColor
unknown
coverFile
file
createdAt
date
creator
user
defaultCard
json
defaultProjectTag
projectTag
description
string
descriptionCoverFile
file
handSyncEnabled
bool
hasGuardians
bool
isDeleted
bool
isOnboardingDeck
bool
manualOrderLabels
json
milestone
milestone
preferredOrder
unknown
project
project
sortValue
string
spaceId
int
stats
json
stickyDefaultProjectTag
bool
title
string
workflowItemOrderLabels
json

Relations

cards
card[]
workflowItems
workflowItem[]
cardOrderInDecks
cardOrderInDeck[]
activities
activity[]

discordGuild

Fields

account
account
createdAt
date
discordGuildId
string
guildIconId
string
guildName
string
karmaRoleThresholds
json
removeCommandEmoji
string
removeCommandEnabled
string
removeCommandRoleId
string
scope
string

Relations

projectNotifications
discordProjectNotification[]
dailyDiscordGuildVoteMemberships
dailyDiscordGuildVoteMembership[]

discordMember

Fields

avatar
string
createdAt
date
deckyScore
int
discordGuild
discordGuild
discordUserId
string
discriminator
string
name
string
nick
string

discordProjectNotification

Fields

createdAt
date
disabledTypes
json
discordChannelId
string
discordGuild
discordGuild
project
project

discordSlashCommand

Fields

autoAddRoleToThread
string
channelId
string
deck
deck
description
string
discordGuild
discordGuild
karmaForCompletion
int
leaderboard
json
maxFileSizeInBytes
int
name
string
permissions
json
reaction
string
reactionThreshold
int
statusMessages
json
statusTargetChannelId
string

dueCard

Fields

account
account
card
card
createdAt
date
user
user

file

Fields

account
account
createdAt
date
deletedAt
date
deletedBy
user
isDeleted
bool
meta
json
name
string
selfHosted
bool
size
string
uploader
user
url
string

handCard

Fields

account
account
card
card
sortIndex
int
user
user

integration

Fields

account
account
createdAt
date
creator
user
disabled
string
type
string
user
user
userData
json
version
int

invoice

Fields

account
account
chargeData
json
charged
int
createdAt
date
invoiceNumber
string
subtotal
int
total
int
url
string

lastSeenCardUpvote

Fields

account
account
createdAt
date
lastSeenAt
date
user
user

milestoneProgress

Fields

milestone
milestone
progress
json

milestoneProject

Fields

account
account
milestone
milestone
project
project

milestone

Fields

account
account
accountSeq
int
color
string
coverFile
file
createdAt
date
creator
user
date
day
description
unknown
handSyncEnabled
bool
isDeleted
bool
isGlobal
bool
manualOrderLabels
json
name
string
preferredOrder
unknown
startDate
day
stats
json
userCapacities
json

Relations

milestoneProjects
milestoneProject[]
cards
card[]
activities
activity[]

pinnedMilestone

Fields

account
account
autoAssignStartedCard
bool
milestone
milestone
sprint
sprint
user
user

projectOrder

Fields

account
account
project
project
sortIndex
string
user
user

projectSelection

Fields

account
account
project
project
user
user

projectTag

Fields

color
string
createdAt
date
description
string
emoji
string
project
project
tag
string

projectUserSetting

Fields

project
project
user
user

projectUser

Fields

account
account
project
project
projectRole
string
user
user

project

Fields

account
account
accountSeq
int
allowUpvotes
bool
commentsArePublic
bool
coverFile
file
createdAt
date
defaultUserAccess
string
effortIcon
unknown
isPublic
bool
markerColor
unknown
name
string
publicBackgroundColor
string
publicBackgroundImage
file
publicBannerFile
file
publicHeading
string
publicIsExplicit
bool
publicLayoutVersion
int
publicMessage
string
publicPath
string
publicRegistryAgreement
bool
publicTileFile
file
spaces
json
visibility
string

Relations

decks
deck[]
milestoneProjects
milestoneProject[]
sprintProjects
sprintProject[]
publicProjectVisits
publicProjectVisit[]
dailyPublicProjectMembership
dailyPublicProjectMembership[]
publicProjectMemberships
publicProjectMembership[]
cardUpvotes
cardUpvote[]
activities
activity[]
explicitProjectUsers
projectUser[]
publicProjectInfo
publicProjectInfo

publicProjectInfo

Fields

account
account
activities7d
string
cardCount
string
cardDoneStreak
string
lastActivityAt
string
project
project
visits7d
string

publicProjectMembership

Fields

createdAt
date
digestFrequencyInDays
int
project
project
user
user

queueEntry

Fields

account
account
card
card
cardDoneAt
date
createdAt
date
sortIndex
int
user
user

queueSelection

Fields

account
account
queueUser
user
sortIndex
int
user
user

release

Fields

content
string
createdAt
date
isLive
string
title
string
version
string

resolvableEntryHistory

Fields

author
user
content
string
lastChangedAt
date
resolvable
resolvable
version
int

resolvableEntry

Fields

author
user
card
card
content
string
createdAt
date
lastChangedAt
date
meta
json
resolvable
resolvable
version
int

Relations

resolvableNotification

Fields

account
account
createdAt
date
isLastParticipant
bool
isParticipating
bool
isSnoozing
bool
lastUpdatedAt
date
latestEntry
resolvableEntry
latestSeenEntry
resolvableEntry
resolvable
resolvable
snoozeUntil
date
unseenAuthors
array
unseenEntryCount
int
user
user

resolvableParticipantHistory

Fields

addedBy
user
done
bool
firstJoinedAt
string
lastChangedAt
date
resolvable
resolvable
status
string
user
user
version
int

resolvableParticipant

Fields

account
account
addedBy
user
discordUserId
string
done
bool
firstJoinedAt
date
lastChangedAt
date
resolvable
resolvable
status
string
user
user

resolvable

Fields

account
account
card
card
closedAt
date
closedBy
user
context
string
contextAsPrio
int
createdAt
date
creator
user
isClosed
bool
isPublic
bool

Relations

savedSearch

Fields

account
account
forceOr
bool
owner
user
tokens
array

sprintConfigProgress

Fields

progress
json
sprintConfig
sprintConfig

sprintConfig

Fields

account
account
autoBeastModeDurationHours
int
beastGracePeriodHours
int
color
string
createdAt
date
creator
user
endHour
int
endHourTimezone
string
isGlobal
bool
moveOnFinish
json
name
string
preferredOrder
unknown
sprintDurationWeeks
int
sprintStartWeekday
int
stopOn
day
upcomingSprints
int

Relations

sprintProgress

Fields

progress
json
sprint
sprint

sprintProject

Fields

account
account
project
project
sprintConfig
sprintConfig

sprint

Fields

account
account
accountSeq
int
autoMilestone
milestone
completedAt
date
coverFile
file
createdAt
date
creator
user
description
string
endDate
day
handSyncEnabled
bool
index
int
isDeleted
bool
lockedAt
date
manualOrderLabels
json
name
string
sprintConfig
sprintConfig
startDate
day
stats
json
userCapacities
json

Relations

cards
card[]
activities
activity[]

stripeAccountSync

Fields

account
account
billingCycleEnd
date
billingCycleStart
date
centsPerSeat
int
euVatIdData
json
grossActualBalance
int
grossBonusBalance
int
hasBeenCancelledAt
date
netGiftBalance
int
paymentMethod
json
pendingPlanType
string
planName
string
planType
string
repeatingCoupon
json
status
string
vatCountryCode
string
vatTaxPercentage
int

timeTrackingSegment

Fields

account
account
addedManually
bool
card
card
createdAt
date
finishedAt
date
modifyDurationMsBy
int
startedAt
date
user
user

timeTrackingSum

Fields

card
card
runningModifyDurationMsBy
int
runningStartedAt
date
sumMs
int
user
user

userDismissedHint

Fields

createdAt
date
hintKey
string
returnAt
date
user
user

userEmail

Fields

createdAt
date
email
string
isPrimary
string
isVerified
string
user
user

userInvitation

Fields

accessToProjectIds
array
account
account
createdAt
date
email
string
inviter
user
role
string

userInviteCode

Fields

accessToProjectIds
array
account
account
createdAt
date
creator
user
isActive
bool
role
string
token
string
useCount
int
validUntil
date

userOnboarding

Fields

steps
json
user
user

userProjectAccess

Fields

project
project
projectRole
string
role
string
user
user

userTag

Fields

account
account
createdAt
date
tag
string
user
user

user

Fields

autoMeFilterCardLimit
int
cdxRole
string
createdAt
date
disableAnimations
bool
disableMovingImages
bool
enableClickToEditCards
bool
fullName
unknown
hasPassword
bool
isIntegration
bool
lastSeenRelease
release
name
string
profileImage
file
showCardIdInTimer
bool
statusColorPalette
string
timezone
string
wantsConvoDigestMail
bool
wantsDailyDigestMail
bool
wantsNewsletter
bool

Relations

projectOrders
projectOrder[]
projectSelections
projectSelection[]
queueSelections
queueSelection[]
accountRoles
accountRole[]
cardDiffNotifications
cardDiffNotification[]
resolvableNotifications
resolvableNotification[]
publicProjectMembership
publicProjectMembership[]
lastSeenCardUpvotes
lastSeenCardUpvote[]
dueCards
dueCard[]
assigneeDeckAssignments
assigneeDeckAssignment[]
savedSearches
savedSearch[]
activities
activity[]
unverifiedEmails
userEmail[]
primaryEmail
userEmail
pinnedMilestoneNext
pinnedMilestone
explicitProjectAccess
projectUser[]
withProjectAccess
userProjectAccess[]
projectSettings
projectUserSetting[]
accountSettings
accountUserSetting[]
dismissedHints
userDismissedHint[]
slackIntegrations
integration[]
activeTimeTracker
activeTimeTracker
userOnboarding
userOnboarding

userReportEmail

Fields

account
account
createdAt
date
email
string
enabled
string
userReportSetting
userReportSetting

userReportSetting

Fields

account
account
createdAt
date
deckMapping
json
fileSizeBytesLimit
bigint
name
string
prioMapping
json

Relations

reportTokens
userReportToken[]

userReportToken

Fields

createdAt
date
enabled
string
label
string
reportCount
int
userReportSetting
userReportSetting

visionBoardProject

Fields

account
account
project
project
visionBoard
visionBoard

visionBoardWidget

Fields

account
account
createdAt
date
creator
user
payload
json
position
unknown
type
string
visionBoard
visionBoard

Relations

visionBoardProjects
visionBoardProject[]

visionBoard

Fields

accessRights
string
account
account
createdAt
date
creator
user
name
string

Relations

visionBoardProjects
visionBoardProject[]

wizard

Fields

account
account
createdAt
date
currentStep
string
data
json
finishedAt
date
name
string

workflowItemHistory

Fields

account
account
changer
user
diff
json
version
int
versionCreatedAt
date

workflowItem

Fields

account
account
accountSeq
int
assignee
user
checkboxInfo
array
checkboxStats
json
content
string
createdAt
date
creator
user
deck
deck
effort
int
label
string
lastUpdatedAt
date
masterTags
array
mentionedUsers
array
priority
unknown
sortOrder
string
sortValue
string
tags
array
targetDeck
deck
title
string
version
string
visibility
string