flatr API documentation

/info

/info

/info

Get info about the API server

Response

Body
Media type: application/json
Type: object
Properties
- version: string (required) | pattern: ^v\d+(\.\d){1,2}$
  Version of the server
  Example
```
v0.1
```
- currentTime: string (required)
  Current time of the server
  Example
```
2018-02-12T15:41:42.799328781Z
```
- name: string (required)
  Name of the implementation of the server
  Example
```
core
```

/invitations

/invitations

/invitations

Get all pending invitations

Request
Response

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: array of Invitation
Items: Invitation
- id: integer (required)
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$
Example
```
[
  {
    "id": 1,
    "email": "flatmate@example.com"
  },
  {
    "id": 3,
    "email": "landlord@example.com"
  }
]
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

/invitations

Invite a person via email address. An email with invite code is sent to them

Request
Response

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: object
Properties:
- email: string (required)
Example
```
{
  "email": "flatmate@example.com"
}
```

Headers
- Location: string (required)
  URL of the newly created Invitation

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
bad_request:
```
{
  "error": {
    "code": "bad_json",
    "message": "The JSON request payload could not be parsed."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
invitation_email_exists:
```
{
  "error": {
    "code": "invitation_email_exists",
    "message": "An invitation with this email address already exists."
  }
}
```

/invitations /{invitationId}

/invitations/{invitationId}

Get information about a specific invitation

Request
Response

URI Parameters
- invitationId: integer (required)

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_found:
```
{
  "error": {
    "code": "not_found",
    "message": "The resource you requested could not be found."
  }
}
```

/invitations/{invitationId}

Resend invitation email

Request
Response

URI Parameters
- invitationId: integer (required)

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: object
Example
```
{}
```

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
bad_request:
```
{
  "error": {
    "code": "bad_json",
    "message": "The JSON request payload could not be parsed."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_found:
```
{
  "error": {
    "code": "not_found",
    "message": "The resource you requested could not be found."
  }
}
```

/invitations/{invitationId}

Delete/Invalidate this invitation

Request
Response

URI Parameters
- invitationId: integer (required)

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Description
Invitation was successfully deleted

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_found:
```
{
  "error": {
    "code": "not_found",
    "message": "The resource you requested could not be found."
  }
}
```

/tasks

/tasks

/tasks

List all tasks

Request
Response

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: array of Task
Items: Task
- id: integer (required)
- title: string (required) | minLength: 1
- description: string (required) | minLength: 1
- frequency: integer (required) | minimum: 1
  Number of days between two executions of this task
- completionTime: integer (required) | minimum: 1
  Time to be allowed for the task to be completed in hours
- users: (array of ) (required)
  All users that will have to complete this task at one point or another.
- currentTurn: union (required)
- upcomingTurns: (array of Turn) (required)
  Items: Turn
  - userId: integer (required)
  - startDate: datetime (required)
Example
```
[
  {
    "id": 1,
    "title": "Doing the dishes",
    "description": "Use soap!",
    "frequency": 3,
    "completionTime": 5,
    "users": [
      1
    ],
    "currentTurn": {
      "userId": 1,
      "startDate": "2018-02-12T04:46:59.234975184Z"
    },
    "upcomingTurns": [
      {
        "userId" : 3,
        "startDate": "2018-02-15T07:00:23.233925184Z"
      }
    ]
  }
]
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

/tasks

Add a new task

Request
Response

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: object
Properties:
- title: string (required) | minLength: 1
- description: string (required) | minLength: 1
- frequency: integer (required) | minimum: 1
  Number of days between two executions of this task
- completionTime: integer (required) | minimum: 1
  Time to be allowed for the task to be completed in hours
- users: (array of ) (required)
  All users that will have to complete this task at one point or another
Example
```
{
  "title": "Doing the dishes",
  "description": "It ain't difficult.",
  "frequency": 3,
  "completionTime": 5,
  "users": [
    1
  ]
}
```

Headers
- Location: string (required)
  URL of the newly created task

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- title: string (required) | minLength: 1
- description: string (required) | minLength: 1
- frequency: integer (required) | minimum: 1
  Number of days between two executions of this task
- completionTime: integer (required) | minimum: 1
  Time to be allowed for the task to be completed in hours
- users: (array of ) (required)
  All users that will have to complete this task at one point or another.
- currentTurn: union (required)
- upcomingTurns: (array of Turn) (required)
  Items: Turn
  - userId: integer (required)
  - startDate: datetime (required)
Example
```
{
  "id": 1,
  "title": "Doing the dishes",
  "description": "Wow, another description here!",
  "frequency": 3,
  "completionTime": 5,
  "users": [
    1
  ],
  "currentTurn": {
    "userId": 1,
    "startDate": "2018-02-12T04:46:59.234975184Z"
  },
  "upcomingTurns": [
    {
      "userId" : 3,
      "startDate": "2018-02-15T07:00:23.233925184Z"
    }
  ]
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
bad_request:
```
{
  "error": {
    "code": "bad_json",
    "message": "The JSON request payload could not be parsed."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

/tasks /{taskId}

/tasks/{taskId}

Get detailed information about a task

Request
Response

URI Parameters
- taskId: integer (required)

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- title: string (required) | minLength: 1
- description: string (required) | minLength: 1
- frequency: integer (required) | minimum: 1
  Number of days between two executions of this task
- completionTime: integer (required) | minimum: 1
  Time to be allowed for the task to be completed in hours
- users: (array of ) (required)
  All users that will have to complete this task at one point or another.
- currentTurn: union (required)
- upcomingTurns: (array of Turn) (required)
  Items: Turn
  - userId: integer (required)
  - startDate: datetime (required)
Example
```
{
  "id": 1,
  "title": "Doing the dishes",
  "description": "This should explain what to do...",
  "frequency": 3,
  "completionTime": 5,
  "users": [
    1
  ],
  "currentTurn": {
    "userId": 1,
    "startDate": "2018-02-12T04:46:59.234975184Z"
  },
  "upcomingTurns": [
    {
      "userId" : 3,
      "startDate": "2018-02-15T07:00:23.233925184Z"
    }
  ]
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_found:
```
{
  "error": {
    "code": "not_found",
    "message": "The resource you requested could not be found."
  }
}
```

/tasks/{taskId}

Delete a task

Request
Response

URI Parameters
- taskId: integer (required)

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Description
Task was successfully deleted

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_found:
```
{
  "error": {
    "code": "not_found",
    "message": "The resource you requested could not be found."
  }
}
```

/tasks/{taskId}

Replace a task and return the same one

Request
Response

URI Parameters
- taskId: integer (required)

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: object
Properties:
- title: string (required) | minLength: 1
- description: string (required) | minLength: 1
- frequency: integer (required) | minimum: 1
  Number of days between two executions of this task
- completionTime: integer (required) | minimum: 1
  Time to be allowed for the task to be completed in hours
- users: (array of ) (required)
  All users that will have to complete this task at one point or another
Example
```
{
  "title": "Doing the dishes",
  "description": "Pretty obvious what to do...",
  "frequency": 3,
  "completionTime": 5,
  "users": [
    1
  ]
}
```

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- title: string (required) | minLength: 1
- description: string (required) | minLength: 1
- frequency: integer (required) | minimum: 1
  Number of days between two executions of this task
- completionTime: integer (required) | minimum: 1
  Time to be allowed for the task to be completed in hours
- users: (array of ) (required)
  All users that will have to complete this task at one point or another.
- currentTurn: union (required)
- upcomingTurns: (array of Turn) (required)
  Items: Turn
  - userId: integer (required)
  - startDate: datetime (required)
Example
```
{
  "id": 1,
  "title": "Doing the dishes",
  "description": "Pretty obvious what to do...",
  "frequency": 3,
  "completionTime": 5,
  "users": [
    1
  ],
  "currentTurn": null,
  "upcomingTurns": [
    {
      "userId" : 3,
      "startDate": "2018-02-15T07:00:23.233925184Z"
    }
  ]
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
bad_request:
```
{
  "error": {
    "code": "bad_json",
    "message": "The JSON request payload could not be parsed."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_found:
```
{
  "error": {
    "code": "not_found",
    "message": "The resource you requested could not be found."
  }
}
```

/tasks/{taskId} /finish

/tasks/{taskId}/finish

Finish the currently active turn of this task

Request
Response

URI Parameters
- taskId: integer (required)

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Description
Task was successfully finished

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_found:
```
{
  "error": {
    "code": "not_found",
    "message": "The resource you requested could not be found."
  }
}
```

/auth

/auth

/auth

Authenticate yourself

Request
Response

Body
Media type: application/json
Type: object
Properties:
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$
- password: string (required) | minLength: 1
Example
```
{
  "email": "john.doe@example.org",
  "password": "pa$$w0rd"
}
```

Body
Media type: application/json
Type: object
Properties
- token: string (required) | pattern: ^[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+$
  JWT token
- tokenId: string (required) | minLength: 20 | maxLength: 20 | pattern: ^[a-zA-Z0-9_-]+$
  JWT ID (jti)
- validFor: integer (required) | minimum: 1
  Validity duration in seconds (excluding server-side grace period)
Example
```
{
  "token": "header.payload.signature",
  "tokenId": "_tokenId000000000000",
  "validFor": 3600
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
bad_request:
```
{
  "error": {
    "code": "bad_json",
    "message": "The JSON request payload could not be parsed."
  }
}
```

Body

Media type: application/json

Type: object

Properties

error: object (required)
- code: string (required) | minLength: 1
- message: string (required)

Examples

email_not_verified:

{
  "error": {
    "code": "email_not_verified",
    "message": "You have not verified your email address yet."
  }
}

credentials_wrong:

{
  "error": {
    "code": "credentials_wrong",
    "message": "User does not exist or password is wrong."
  }
}

user_disabled:

{
  "error": {
    "code": "user_disabled",
    "message": "This user is disabled and has to be enabled before being able to log in."
  }
}

/users

/users

/users

Get all users

Request
Response

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: array of User
Items: User
- id: integer (required)
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$
- firstName: string (required) | minLength: 1
- lastName: string (required) | minLength: 1
- emailVerified: boolean (required)
- disabled: boolean (required)
- absent: boolean (required)
Example
```
[
  {
    "id": 1,
    "email": "ds@example.org",
    "firstName": "Daniel",
    "lastName": "Schäfer",
    "emailVerified": true,
    "disabled": false,
    "absent": false
  }
]
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

/users

Request
Response

Body

Media type: application/json

Type: InvitationRegistration | EmailRegistration

Examples

with_invitation_code:

{
  "firstName": "Daniel",
  "lastName": "Schäfer",
  "password": "pa$$w0rd",
  "invitationCode": "9d0d1e5f8dbe5dc0",
  "absent": false
}

with_email:

{
  "firstName": "Daniel",
  "lastName": "Schäfer",
  "password": "pa$$w0rd",
  "email": "foo@example.org",
  "absent": false
}

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$
- firstName: string (required) | minLength: 1
- lastName: string (required) | minLength: 1
- emailVerified: boolean (required)
- disabled: boolean (required)
- absent: boolean (required)

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
bad_request:
```
{
  "error": {
    "code": "bad_json",
    "message": "The JSON request payload could not be parsed."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_invite:
```
{
  "error": {
    "code": "not_invited",
    "message": "Your email address is not invited."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
invitation_code_invalid:
```
{
  "error": {
    "code": "invitation_code_invalid",
    "message": "This is not a valid invitation code."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
email_exists:
```
{
  "error": {
    "code": "email_exists",
    "message": "A user with this email address already exists."
  }
}
```

/users /{userId}

/users/{userId}

Get the user with this Id

Request
Response

URI Parameters
- userId: string (required)

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$
- firstName: string (required) | minLength: 1
- lastName: string (required) | minLength: 1
- emailVerified: boolean (required)
- disabled: boolean (required)
- absent: boolean (required)

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_found:
```
{
  "error": {
    "code": "not_found",
    "message": "The resource you requested could not be found."
  }
}
```

/users/{userId}

Delete the user with this id

Request
Response

URI Parameters
- userId: string (required)

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Description
User was successfully deleted

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
not_found:
```
{
  "error": {
    "code": "not_found",
    "message": "The resource you requested could not be found."
  }
}
```

/users /verify

/users/verify

Verify the email of a user by providing the code sent to him in an email.

Request
Response

Body
Media type: application/json
Type: object
Properties:
- code: string (required)

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$
- firstName: string (required) | minLength: 1
- lastName: string (required) | minLength: 1
- emailVerified: boolean (required)
- disabled: boolean (required)
- absent: boolean (required)

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
bad_request:
```
{
  "error": {
    "code": "bad_json",
    "message": "The JSON request payload could not be parsed."
  }
}
```

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
verification_code_invalid:
```
{
  "error": {
    "code": "verification_code_invalid",
    "message": "Your email address could not be verified with this code."
  }
}
```

/users /current

/users/current

Get the currently logged in user

Request
Response

Headers
- Authorization: string (required)
  Auth token
  Example
```
Bearer $token
```

Body
Media type: application/json
Type: object
Properties
- id: integer (required)
- email: string (required) | minLength: 1 | pattern: ^.+@.+\..+$
- firstName: string (required) | minLength: 1
- lastName: string (required) | minLength: 1
- emailVerified: boolean (required)
- disabled: boolean (required)
- absent: boolean (required)

Body
Media type: application/json
Type: object
Properties
- error: object (required)
  - code: string (required) | minLength: 1
  - message: string (required)
Example
unauthorized:
```
{
  "error": {
    "code": "unauthorized",
    "message": "You are not authorized to access this resource."
  }
}
```