Introduction

Welcome to the Chorescore API! You can use our API to access Chorescore API endpoints.

Preconditions

You can expect every getAll request to return an object with a key "entries" and the individual objects.

Get All Response Object

{
  "entries": [
  ..
  ]
}

Authentication

Authorize

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl --form user=YOUR-USER \
     --form pin=YOUR-PIN \
     "https://chorescore.confusedoncoffee.com:4444/api/token/authorize"

client := resty.New()
client.POST(https://chorescore.confusedoncoffee.com:4444/api/v1/token/authorize)

Response

{
  "accessToken": "chs-650417e091a25f42f05a972e826a35b3890594a4",
  "refreshToken": "db95622dc5160f210008597a8daf1c7d31ed09b7"
}

Make sure to replace YOUR-PERSONAL-ACCESS-TOKEN with your API key.

Chorescore uses API keys to allow access to the API. You can register a new Chorescore API key at our developer portal.

Chorescore expects for the API key to be included in all API requests to the server in a header that looks like the following:

x-chorescore-api-key: YOUR-PERSONAL-ACCESS-TOKEN

You must replace YOUR-PERSONAL-ACCESS-TOKEN with your personal API key.

Tokeinfo

curl -H "x-chorescore-api-key: YOUR-PERSONAL-ACCESS-TOKEN"\
     "https://chorescore.confusedoncoffee.com:4444/api/token/info"

Response

{
  "access_token": "chs-278d0d3a708e0c15e055a6f37dd87314d77ca60e",
  "expires_at": "Thu, 09 Jan 2025 19:37:02 +0100",
  "expires_in": 1736447822953,
  "issues_at": 1736015822953,
  "refresh_token": "1a9123f5494c45893658796bf827983f2ad96612",
  "role": "ADMIN",
  "scope": "api",
  "sub": "df81632b71983befbd03a9f4baea50d19aa0b6ce52ea712137fc23330137b026f1fbf2c584",
  "token_type": "Bearer"
}

Refresh

To authorize, use this code:

curl -d "grant_type=refresh_token&refresh_token=[your-refres-token]" \
     -X 'POST' \
     -H 'content-type: application/x-www-form-urlencoded' \
     "https://chorescore.confusedoncoffee.com:4444/api/token/refresh"

Response returns a new token object as it would be in /api/token/info

Invalidate

curl -H "x-chorescore-api-key: YOUR-PERSONAL-ACCESS-TOKEN" \
     "https://chorescore.confusedoncoffee.com:4444/api/token/invalidate"

Response is Accepted 202

Teams

Get All Teams

curl "https://chorescore.confusedoncoffee.com:4444/api/v1/teams" \
  -H "Authorization: YOUR-PERSONAL-ACCESS-TOKEN"

The above command returns JSON structured like this:

{
  "entries": [
    {
      "color": "#f5ec00",
      "createdAt": 1711202458366,
      "createdBy": "weiky",
      "id": "b987c144-720d-4a64-bb33-3c0a141d072d",
      "members": [
        ...
      ],
      "name": "WeiKatha",
      "public": true,
      "ruleSet": {
        "id": "7e4b6a2c-507f-4cfe-b2b3-fe4e41d5fea4",
        "name": "Classic",
        "version": 1
      },
      "score": 1,
      "tags": [
        "weiky"
      ],
      "taskSet": {
        "name": "",
        "version": 0
      },
      "tasks": [
        ...
      ],
      "version": 0,
      "versionSettings": {
        "id": "7e4b6a2c-507f-4cfe-b2b3-fe4e41d5fea4",
        "name": "Classic",
        "version": 1
      }
    },
    {
      "color": "#3a87fe",
      "createdAt": 1711290352956,
      "createdBy": "susl",
      "id": "190cd1dc-4b9e-44a4-9278-9af4c38f2ba0",
      "members": [
        ...
      ],
      "name": "HustleClub",
      "public": false,
      "ruleSet": {
        "id": "7e4b6a2c-507f-4cfe-b2b3-fe4e41d5fea4",
        "name": "7e4b6a2c",
        "version": 1
      },
      "score": 10,
      "tags": [
        "susl"
      ],
      "taskSet": {
        "name": "",
        "version": 0
      },
      "tasks": [
       ...
      ],
      "version": 0,
      "versionSettings": {
        "id": "7e4b6a2c-507f-4cfe-b2b3-fe4e41d5fea4",
        "name": "7e4b6a2c",
        "version": 1
      }
    },

  ]
}

This endpoint retrieves all kittens.

HTTP Request

GET https://chorescore.confusedoncoffee.com:4444/api/v1/teams

Query Parameters

Parameter	Default	Description
public	true	If set to true, the result will only include public teams
byMe	false	If set to false, the result will include only teams created by you.

Get a Specific Teams

curl -H "Authorization: YOUR-PERSONAL-ACCESS-TOKEN" \
  "https://chorescore.confusedoncoffee.com:4444/api/v1/teams/<ID>"

The above command returns JSON structured like this:

{
  "color": "#ffab01",
  "createdAt": 1711203707894,
  "createdBy": "testuser",
  "id": "5b225917-8368-45d4-9f67-3a5d3c82d5d8",
  "members": [
    {
      "id": "d6d7f4e1-634e-49b6-be84-eb53812726ac",
      "name": "owl"
    }
  ],
  "name": "teamname",
  "public": true,
  "quests": [],
  "ruleSet": {
    "id": "7e4b6a2c-507f-4cfe-b2b3-fe4e41d5fea4",
    "name": "Classic",
    "version": 1
  },
  "score": 62,
  "tags": ["testuser"],
  "taskSet": {
    "name": "",
    "version": 0
  },
  "tasks": [
    {
      "createdAt": 1711203707893,
      "createdBy": "testuser",
      "expiresAt": 1711290107893,
      "id": "929adf5f-3914-4ff4-bbf7-0c0b497d137e",
      "interval": "DAILY",
      "name": "Example tasks",
      "point": 6,
      "public": true,
      "readySince": 0,
      "scored": [],
      "seeded": 6,
      "startedSince": 0,
      "up": true
    },
    {
      "createdAt": 1711203707894,
      "createdBy": "testuser",
      "expiresAt": 1711290107894,
      "id": "bc2a1052-b10d-4555-aeaa-002c18eac946",
      "interval": "DAILY",
      "name": "Example task2",
      "point": 4,
      "public": true,
      "readySince": 0,
      "scored": [],
      "seeded": 4,
      "startedSince": 0,
      "up": true
    }
  ],
  "version": 0,
  "versionSettings": {
    "id": "7e4b6a2c-507f-4cfe-b2b3-fe4e41d5fea4",
    "name": "Classic",
    "version": 1
  }
}

HTTP Request

GET https://chorescore.confusedoncoffee.com:4444/api/v1/teams/<ID>

Delete a Team

curl -X DELETE \
     -H "Authorization: YOUR-PERSONAL-ACCESS-TOKEN" \
     https://chorescore.confusedoncoffee.com:4444/api/v1/teams/<ID>

The above command returns JSON structured like this:

{
  "id": 2
}

This endpoint deletes a specific team.

HTTP Request

curl -X DELETE \
     -H "Authorization: YOUR-PERSONAL-ACCESS-TOKEN" \
     https://chorescore.confusedoncoffee.com:4444/api/v1/teams/<ID>

URL Parameters

Parameter	Description
ID	The ID of the teams to delete

Tasks

Get All Tasks

curl "https://chorescore.confusedoncoffee.com:4444/api/v1/tasks" \
  -H "Authorization: YOUR-PERSONAL-ACCESS-TOKEN"

The above command returns JSON structured like this:

{
  "entries": [
    {
      "createdAt": 1711203707893,
      "createdBy": "testuser",
      "expiresAt": 1711290107893,
      "id": "929adf5f-3914-4ff4-bbf7-0c0b497d137e",
      "interval": "DAILY",
      "name": "Example tasks",
      "point": 6,
      "public": true,
      "readySince": 0,
      "scored": [],
      "seeded": 6,
      "startedSince": 0,
      "up": true
    },
    {
      "createdAt": 1711203707894,
      "createdBy": "testuser",
      "expiresAt": 1711290107894,
      "id": "bc2a1052-b10d-4555-aeaa-002c18eac946",
      "interval": "DAILY",
      "name": "Example task2",
      "point": 4,
      "public": true,
      "readySince": 0,
      "scored": [],
      "seeded": 4,
      "startedSince": 0,
      "up": true
    }
  ]
}

This endpoint retrieves all kittens.

HTTP Request

GET https://chorescore.confusedoncoffee.com:4444/api/v1/tasks

Query Parameters

Parameter	Default	Description
public	true	If set to true, the result will only include public tasks
byMe	false	If set to false, the result will include only tasks created by you.

Get a Specific Task

curl -H "Authorization: YOUR-PERSONAL-ACCESS-TOKEN" \
     https://chorescore.confusedoncoffee.com:4444/api/v1/tasks/<ID>

The above command returns JSON structured like this:

{
  "createdAt": 1711203707893,
  "createdBy": "testuser",
  "expiresAt": 1711290107893,
  "id": "929adf5f-3914-4ff4-bbf7-0c0b497d137e",
  "interval": "DAILY",
  "name": "Example tasks",
  "point": 6,
  "public": true,
  "readySince": 0,
  "scored": [],
  "seeded": 6,
  "startedSince": 0,
  "up": true
}

HTTP Request

GET https://chorescore.confusedoncoffee.com:4444/api/v1/tasks/<ID>

Delete a Task

curl -X DELETE \
     -H "Authorization: YOUR-PERSONAL-ACCESS-TOKEN" \
     https://chorescore.confusedoncoffee.com:4444/api/v1/tasks/<ID>

The above command returns JSON structured like this:

{
  "id": 2
}

This endpoint deletes a specific tasks.

HTTP Request

curl -X DELETE \
     -H "Authorization: YOUR-PERSONAL-ACCESS-TOKEN" \
     https://chorescore.confusedoncoffee.com:4444/api/v1/tasks/<ID>

URL Parameters

Parameter	Description
ID	The ID of the tasks to delete

Errors

The API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
423	Malinformed body
500	Internal Server Error -- We had a problem with our server. Try again later.

Terminology

Teams

Bundles teams, tasks, members, quest and rules into one object. This is a core object.

RuleSet

Bundles different rules for one team.

PauseHistory

Shows the history, when a team was paused.

IdentifierTuple

Delivers name and uuid tuples for members or teams.

Quest

Contains the tasks, which are time sensitive.

HistoryTask

Contains the history, when a task was done, completed or archived.

Structs

Backend Features

A feature defintion contains the state (active), when it was active, the ID and which guards protect its. Further this response tells, when the last change occured (updatedOn)

Key	Description
active	If the feature is enabled
activeSince	When was the feature enabled
featureId	Id

Guards

A special case is the GETALL. It allows requesting all artifacts of the specified type, in combination with the user, who does the request and if the artfifact is public or not.

Key	Description
alias	GETALL, GET, POST, PUT (the methods)
enabled	If the method is allowed
requires	The role it requires


{
  "features": [
    {
      "active": true,
      "activeSince": 1734587864474,
      "featureId": "f-features-vote",
      "guards": [
        {
          "alias": "GETALL",
          "enabled": true,
          "requires": "MODERATOR"
        },
        {
          "alias": "GET",
          "enabled": true,
          "requires": "MODERATOR"
        },
        {
          "alias": "POST",
          "enabled": true,
          "requires": "MODERATOR"
        },
        {
          "alias": "PUT",
          "enabled": true,
          "requires": "MODERATOR"
        },
        {
          "alias": "DELETE",
          "enabled": true,
          "requires": "MODERATOR"
        }
      ],
      "state": 0,
      "type": "Feature"
    }
  ],
  updatedOn 1734587864474
}

Health

A cute information message for admin statistics.

Key	Description
metadata	Contains links and names, used in the about page
reset	If the UI local storage should be reset.
token	The admin token to do a first request.
upSince	The time since the server is started.
version	The deployed version.

{
  "metadata": {
  ...
  }
  "message": "Actually this means, we are running for 23297 minutes. Well done :)! Why do you read this?",
  "reset": false,
  "state": "HEALTHY",
  "token": "",
  "upSince": "2024-12-19T05:57:44Z",
  "version": "2024.12.12-d158bad"
}

Status

This serves are specific status message put in by the server admin

{
  "level": "info",
  "msg": "I wish you a good festive time. :)",
  "title": "HAPPY HOLIDAYS",
  "version": "2024.12.12-d158bad"
}

Theme

A fun feature to replace icons. This replacees the defined icons with the use icons in the given time (startsAt -> endsAt)

Definition

Keys	Type	Description
endsAt, startsAt	string	time date in format YYYY-MM-DD
icons, use	string[]	The icon ids
them	string	The name of the theme

{
  "endsAt": "YYYY-MM-DD",
  "icons": "string[]],
  "startsAt": "YYYY-MM-DD",
  "theme": "string",
  "use": "string[]"
}

Example for a winter theme

{
  "endsAt": "2025-01-15",
  "icons": ["at", "list_task", "house", "house-check", "people"],
  "startsAt": "2024-12-01",
  "theme": "Winter",
  "use": ["star", "stars", "magic"]
}

User

A user is a user and he can be a member if he part of a team.

Key	Type	Description
color	string	the user color
name	string	the user name
id	string	The settings id
role	string	User role
tags	string[]	Associated tags
teamTuples	IdentifierTuple[]	this wil be populated by IdentifierTuple

{
  "color": "#8d8602",
  "id": "2a01a4d3-fe2d-4a58-a43f-84cdfa48b90a",
  "name": "admin",
  "role": "ADMIN",
  "tags": ["admin"],
  "teamTuples": null
}

User Settings

Settings of the user are saved in the BE. They contain the recently used artifacts, favourites artifacts and how the team dashboard is configured.

Key	Type	Description
advancedMode	boolean	Has sidebar with advanced option open
appTheme	object	Contains information about the selected theme
artifactViewMode	string	The mode in which the artifacts are shown
assistance	boolean	If the info-modal should be shown, when using the UI
dashboard	object	How the team dashboard is served
favourites	object	The saved favourites for the user
id	string	The settings id
lastOnline	number	When was the user last online
navigationMode	string	The LEGACY navigation bar mode
preferences	object	In which order are task shown in the team dashboard
previous	object	The previous selected artifacts
recent	object	The recent selected artfiacts
tasks	object	Which task are shown in the team dashboard

{
  "advancedMode": false,
  "appTheme": {
    "custom": false,
    "nightMode": false,
    "theme": null
  },
  "artifactsViewMode": "rows",
  "assistance": {
    "assistance": false,
    "info": true
  },
  "dashboard": {
    "dashboard": null,
    "minimized": false
  },
  "favourites": {
    "tasks": [],
    "teams": []
  },
  "id": "2a01a4d3-fe2d-4a58-a43f-84cdfa48b90a",
  "lastOnline": 1735985671801,
  "navigationMode": "classic",
  "preferences": {
    "alreadyOpen": false,
    "public": false,
    "taskInterval": null
  },
  "previous": {
    "rule": null,
    "settings": null,
    "task": null,
    "team": null
  },
  "recents": {
    "tasks": [],
    "teams": []
  },
  "tasks": {
    "onlyMe": false,
    "showAssignment": false,
    "taskDetails": false
  },
  "userName": "admin"
}

Team

Bundles teams, tasks, members, quest and rules into one object. This is a core object.

{
  "color": "#ffab01",
  "createdAt": 1711203707894,
  "createdBy": "testuser",
  "id": "5b225917-8368-45d4-9f67-3a5d3c82d5d8",
  "members": [
    {
      "id": "d6d7f4e1-634e-49b6-be84-eb53812726ac",
      "name": "owl"
    }
  ],
  "name": "teamname",
  "public": true,
  "quests": [],
  "ruleSet": {
    "id": "7e4b6a2c-507f-4cfe-b2b3-fe4e41d5fea4",
    "name": "Classic",
    "version": 1
  },
  "score": 62,
  "tags": ["testuser"],
  "taskSet": {
    "name": "",
    "version": 0
  },
  "tasks": [
    {
      "createdAt": 1711203707893,
      "createdBy": "testuser",
      "expiresAt": 1711290107893,
      "id": "929adf5f-3914-4ff4-bbf7-0c0b497d137e",
      "interval": "DAILY",
      "name": "Example tasks",
      "point": 6,
      "public": true,
      "readySince": 0,
      "scored": [],
      "seeded": 6,
      "startedSince": 0,
      "up": true
    },
    {
      "createdAt": 1711203707894,
      "createdBy": "testuser",
      "expiresAt": 1711290107894,
      "id": "bc2a1052-b10d-4555-aeaa-002c18eac946",
      "interval": "DAILY",
      "name": "Example task2",
      "point": 4,
      "public": true,
      "readySince": 0,
      "scored": [],
      "seeded": 4,
      "startedSince": 0,
      "up": true
    }
  ],
  "version": 0,
  "versionSettings": {
    "id": "7e4b6a2c-507f-4cfe-b2b3-fe4e41d5fea4",
    "name": "Classic",
    "version": 1
  }
}

Task

A task:

must be completed by a member of a team
must be public or private
must have a interval, when this task is to completed
must have points, which the assignee receives once completed

{
  "createdAt": 1711831763436,
  "createdBy": "owl",
  "expiresAt": 0,
  "id": "0660e0c4-3fbe-4789-81e9-2835bb11579d",
  "interval": "DAILY",
  "name": "Task name",
  "point": 3,
  "public": true,
  "readySince": 0,
  "scored": null,
  "seeded": 0,
  "startedSince": 0,
  "tags": ["food", "fun"],
  "up": false
}

RuleSet

Bundles different rules for one team.

Task Rule

{
  "createdAt": 1710969925657,
  "createdBy": "",
  "id": "a75b546b-1008-43e3-a29d-c73e3a1ce3c5",
  "name": "Classic",
  "public": true,
  "rule": {
    "interval": 24,
    "ratio": 1.5
  },
  "tags": [""],
  "target": "Task",
  "version": 1
}

Team Rule

{
  "createdAt": 1713600547742,
  "createdBy": "admin",
  "id": "654fbce5-497c-45a0-bd22-2fb1da6a3dbc",
  "name": "Quests",
  "public": true,
  "rule": {
    "amount": 1,
    "awards": false,
    "bet": false,
    "confirmation": false,
    "identifier": "Quests-1-admin",
    "quests": true,
    "teamSteps": 1,
    "teamStreak": null,
    "type": "TEAM"
  },
  "tags": ["quests"],
  "target": "Team",
  "version": 1
}

PauseHistory

Shows the history, when a team was paused.

IdentifierTuple

Delivers name and uuid tuples for members or teams.

Quest

Contains the tasks, which are time sensitive. A quest is:

a task, which needs to be completed in a given time by a user
created by a member of the team
happening only once

HistoryTask

Contains the history, when a task was done, completed or archived.

Scores

A score is a simple object, which contains the score for the team (name, team) and when it scored last.

[
  {
    "name": "oskar",
    "score": 155,
    "scoredAt": 1712855588636,
    "team": "0762edc9-b80f-4330-aa49-a6e9eb725de3"
  },
  {
    "name": "owl",
    "score": 20,
    "scoredAt": 1712999703814,
    "team": "8d81cbaf-513c-4cc0-92ee-3ca975863469"
  }
]

Themes

A theme contains the information how to style the CSS and overwrite the variables. Accent, background, primary, text and error are colors.

{
  "accent": "#0061fe",
  "background": "#445d00",
  "createdAt": 1713688828355,
  "createdBy": "owl",
  "error": "#b51a00",
  "id": "0ce29082-e6a3-44c5-bb01-b84a67b83fed",
  "name": "Natur 3",
  "primary": "#ff4036",
  "public": false,
  "tags": ["nature"],
  "text": "#000000",
  "version": 0,
  "votes": null,
  "warn": "#d38301"
}

CHORESCORE

API DOCUMENTATION

Introduction

Preconditions

Get All Response Object

Authentication

Authorize

Tokeinfo

Refresh

Invalidate

Teams

Get All Teams

HTTP Request

Query Parameters

Get a Specific Teams

HTTP Request

Delete a Team

HTTP Request

URL Parameters

Tasks

Get All Tasks

HTTP Request

Query Parameters

Get a Specific Task

HTTP Request

Delete a Task

HTTP Request

URL Parameters

Errors

Terminology

Teams

RuleSet

PauseHistory

IdentifierTuple

Quest

HistoryTask

Structs

Backend Features

Guards

Health

Status

Theme

Definition

User

User Settings

Team

Task

RuleSet

Task Rule

Team Rule

PauseHistory

IdentifierTuple

Quest

HistoryTask

Scores

Themes