vikunja/pkg/swagger/swagger.yaml

6573 lines
189 KiB
YAML
Raw Normal View History

basePath: /api/v1
definitions:
auth.Token:
properties:
token:
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
type: string
type: object
background.Image:
properties:
blur_hash:
type: string
id:
type: string
info:
description: This can be used to supply extra information from an image provider
to clients
thumb:
type: string
url:
type: string
type: object
files.File:
properties:
created:
type: string
id:
type: integer
mime:
type: string
name:
type: string
size:
type: integer
type: object
handler.AuthURL:
properties:
url:
type: string
type: object
microsofttodo.Migration:
properties:
code:
type: string
type: object
migration.Status:
properties:
2023-11-08 23:29:34 +00:00
finished_at:
type: string
id:
type: integer
migrator_name:
type: string
2023-11-08 23:29:34 +00:00
started_at:
type: string
type: object
models.APIPermissions:
additionalProperties:
items:
type: string
type: array
type: object
models.APIToken:
properties:
created:
description: A timestamp when this api key was created. You cannot change
this value.
type: string
expires_at:
description: The date when this key expires.
type: string
id:
description: The unique, numeric id of this api key.
type: integer
permissions:
allOf:
- $ref: '#/definitions/models.APIPermissions'
description: The permissions this token has. Possible values are available
via the /routes endpoint and consist of the keys of the list from that endpoint.
For example, if the token should be able to read all tasks as well as update
existing tasks, you should add `{"tasks":["read_all","update"]}`.
title:
description: A human-readable name for this token
type: string
token:
description: The actual api key. Only visible after creation.
type: string
type: object
models.APITokenRoute:
2024-06-03 19:51:44 +00:00
additionalProperties:
$ref: '#/definitions/models.RouteDetail'
type: object
models.Bucket:
properties:
count:
description: The number of tasks currently in this bucket
type: integer
created:
description: A timestamp when this bucket was created. You cannot change this
value.
type: string
created_by:
allOf:
- $ref: '#/definitions/user.User'
description: The user who initially created the bucket.
id:
description: The unique, numeric id of this bucket.
type: integer
limit:
description: How many tasks can be at the same time on this board max
minimum: 0
type: integer
position:
description: The position this bucket has when querying all buckets. See the
tasks.position property on how to use this.
type: number
2024-03-15 22:19:26 +01:00
project_view_id:
description: The project view this bucket belongs to.
type: integer
tasks:
description: All tasks which belong to this bucket.
items:
$ref: '#/definitions/models.Task'
type: array
title:
description: The title of this bucket.
minLength: 1
type: string
updated:
description: A timestamp when this bucket was last updated. You cannot change
this value.
type: string
type: object
2024-03-15 22:19:26 +01:00
models.BucketConfigurationModeKind:
enum:
- 0
- 1
- 2
type: integer
x-enum-varnames:
- BucketConfigurationModeNone
- BucketConfigurationModeManual
- BucketConfigurationModeFilter
models.BulkAssignees:
properties:
assignees:
description: A project with all assignees
items:
$ref: '#/definitions/user.User'
type: array
type: object
models.BulkTask:
properties:
assignees:
description: An array of users who are assigned to this task
items:
$ref: '#/definitions/user.User'
type: array
attachments:
description: All attachments this task has
items:
$ref: '#/definitions/models.TaskAttachment'
type: array
bucket_id:
2024-03-15 22:19:26 +01:00
description: |-
The bucket id. Will only be populated when the task is accessed via a view with buckets.
Can be used to move a task between buckets. In that case, the new bucket must be in the same view as the old one.
type: integer
cover_image_attachment_id:
description: If this task has a cover image, the field will return the id
of the attachment that is the cover image.
type: integer
created:
description: A timestamp when this task was created. You cannot change this
value.
type: string
created_by:
allOf:
- $ref: '#/definitions/user.User'
description: The user who initially created the task.
description:
description: The task description.
type: string
done:
description: Whether a task is done or not.
type: boolean
done_at:
description: The time when a task was marked as done.
type: string
due_date:
description: The time when the task is due.
type: string
end_date:
description: When this task ends.
type: string
hex_color:
description: The task color in hex
2023-10-24 14:38:04 +00:00
maxLength: 7
type: string
id:
description: The unique, numeric id of this task.
type: integer
identifier:
description: The task identifier, based on the project identifier and the
task's index
type: string
index:
description: The task index, calculated per project
type: integer
is_favorite:
description: True if a task is a favorite task. Favorite tasks show up in
a separate "Important" project. This value depends on the user making the
call to the api.
type: boolean
labels:
description: An array of labels which are associated with this task.
items:
$ref: '#/definitions/models.Label'
type: array
percent_done:
description: Determines how far a task is left from being done
type: number
position:
description: |-
The position of the task - any task project can be sorted as usual by this parameter.
2024-03-15 22:19:26 +01:00
When accessing tasks via views with buckets, this is primarily used to sort them based on a range.
Positions are always saved per view. They will automatically be set if you request the tasks through a view
endpoint, otherwise they will always be 0. To update them, take a look at the Task Position endpoint.
type: number
priority:
description: The task priority. Can be anything you want, it is possible to
sort by this later.
type: integer
project_id:
description: The project this task belongs to.
type: integer
2024-03-12 19:47:16 +00:00
reactions:
allOf:
- $ref: '#/definitions/models.ReactionMap'
description: Reactions on that task.
related_tasks:
allOf:
- $ref: '#/definitions/models.RelatedTaskMap'
description: All related tasks, grouped by their relation kind
reminders:
description: An array of reminders that are associated with this task.
items:
$ref: '#/definitions/models.TaskReminder'
type: array
repeat_after:
description: An amount in seconds this task repeats itself. If this is set,
when marking the task as done, it will mark itself as "undone" and then
increase all remindes and the due date by its amount.
type: integer
repeat_mode:
allOf:
- $ref: '#/definitions/models.TaskRepeatMode'
description: 'Can have three possible values which will trigger when the task
is marked as done: 0 = repeats after the amount specified in repeat_after,
1 = repeats all dates each months (ignoring repeat_after), 3 = repeats from
the current date rather than the last set date.'
start_date:
description: When this task starts.
type: string
subscription:
allOf:
- $ref: '#/definitions/models.Subscription'
description: |-
The subscription status for the user reading this task. You can only read this property, use the subscription endpoints to modify it.
Will only returned when retrieving one task.
task_ids:
description: A project of task ids to update
items:
type: integer
type: array
title:
description: The task text. This is what you'll see in the project.
minLength: 1
type: string
updated:
description: A timestamp when this task was last updated. You cannot change
this value.
type: string
type: object
models.DatabaseNotifications:
properties:
created:
description: A timestamp when this notification was created. You cannot change
this value.
type: string
id:
description: The unique, numeric id of this notification.
type: integer
name:
description: The name of the notification
type: string
notification:
description: The actual content of the notification.
read:
description: |-
Whether or not to mark this notification as read or unread.
True is read, false is unread.
type: boolean
read_at:
description: When this notification is marked as read, this will be updated
with the current timestamp.
type: string
type: object
models.Label:
properties:
created:
description: A timestamp when this label was created. You cannot change this
value.
type: string
created_by:
allOf:
- $ref: '#/definitions/user.User'
description: The user who created this label
description:
description: The label description.
type: string
hex_color:
2023-10-24 14:38:04 +00:00
description: The color this label has in hex format.
maxLength: 7
type: string
id:
description: The unique, numeric id of this label.
type: integer
title:
description: The title of the lable. You'll see this one on tasks associated
with it.
maxLength: 250
minLength: 1
type: string
updated:
description: A timestamp when this label was last updated. You cannot change
this value.
type: string
type: object
models.LabelTask:
properties:
created:
description: A timestamp when this task was created. You cannot change this
value.
type: string
label_id:
description: The label id you want to associate with a task.
type: integer
type: object
models.LabelTaskBulk:
properties:
labels:
description: All labels you want to update at once.
items:
$ref: '#/definitions/models.Label'
type: array
type: object
models.LinkSharing:
properties:
created:
description: A timestamp when this project was shared. You cannot change this
value.
type: string
hash:
description: The public id to get this shared project
type: string
id:
description: The ID of the shared thing
type: integer
name:
description: The name of this link share. All actions someone takes while
being authenticated with that link will appear with that name.
type: string
password:
description: The password of this link share. You can only set it, not retrieve
it after the link share has been created.
type: string
right:
allOf:
- $ref: '#/definitions/models.Right'
default: 0
description: The right this project is shared with. 0 = Read only, 1 = Read
& Write, 2 = Admin. See the docs for more details.
maximum: 2
shared_by:
allOf:
- $ref: '#/definitions/user.User'
description: The user who shared this project
sharing_type:
allOf:
- $ref: '#/definitions/models.SharingType'
default: 0
description: The kind of this link. 0 = undefined, 1 = without password, 2
= with password.
maximum: 2
updated:
description: A timestamp when this share was last updated. You cannot change
this value.
type: string
type: object
models.Message:
properties:
message:
description: A standard message.
type: string
type: object
models.Project:
properties:
background_blur_hash:
description: Contains a very small version of the project background to use
as a blurry preview until the actual background is loaded. Check out https://blurha.sh/
to learn how it works.
type: string
background_information:
description: Holds extra information about the background set since some background
providers require attribution or similar. If not null, the background can
be accessed at /projects/{projectID}/background
created:
description: A timestamp when this project was created. You cannot change
this value.
type: string
description:
description: The description of the project.
type: string
hex_color:
description: The hex color of this project
2023-10-24 14:38:04 +00:00
maxLength: 7
type: string
id:
description: The unique, numeric id of this project.
type: integer
identifier:
description: The unique project short identifier. Used to build task identifiers.
maxLength: 10
minLength: 0
type: string
is_archived:
description: Whether a project is archived.
type: boolean
is_favorite:
description: True if a project is a favorite. Favorite projects show up in
a separate parent project. This value depends on the user making the call
to the api.
type: boolean
owner:
allOf:
- $ref: '#/definitions/user.User'
description: The user who created this project.
parent_project_id:
type: integer
position:
description: The position this project has when querying all projects. See
the tasks.position property on how to use this.
type: number
subscription:
allOf:
- $ref: '#/definitions/models.Subscription'
description: |-
The subscription status for the user reading this project. You can only read this property, use the subscription endpoints to modify it.
Will only returned when retreiving one project.
title:
description: The title of the project. You'll see this in the overview.
maxLength: 250
minLength: 1
type: string
updated:
description: A timestamp when this project was last updated. You cannot change
this value.
type: string
2024-03-15 22:19:26 +01:00
views:
items:
$ref: '#/definitions/models.ProjectView'
type: array
type: object
models.ProjectDuplicate:
properties:
duplicated_project:
allOf:
- $ref: '#/definitions/models.Project'
description: The copied project
parent_project_id:
description: The target parent project
type: integer
type: object
models.ProjectUser:
properties:
created:
description: A timestamp when this relation was created. You cannot change
this value.
type: string
id:
description: The unique, numeric id of this project <-> user relation.
type: integer
right:
allOf:
- $ref: '#/definitions/models.Right'
default: 0
description: The right this user has. 0 = Read only, 1 = Read & Write, 2 =
Admin. See the docs for more details.
maximum: 2
updated:
description: A timestamp when this relation was last updated. You cannot change
this value.
type: string
user_id:
description: The username.
type: string
type: object
2024-03-15 22:19:26 +01:00
models.ProjectView:
properties:
bucket_configuration:
description: When the bucket configuration mode is not `manual`, this field
holds the options of that configuration.
items:
$ref: '#/definitions/models.ProjectViewBucketConfiguration'
type: array
bucket_configuration_mode:
allOf:
- $ref: '#/definitions/models.BucketConfigurationModeKind'
description: The bucket configuration mode. Can be `none`, `manual` or `filter`.
`manual` allows to move tasks between buckets as you normally would. `filter`
creates buckets based on a filter for each bucket.
created:
description: A timestamp when this reaction was created. You cannot change
this value.
type: string
default_bucket_id:
description: The ID of the bucket where new tasks without a bucket are added
to. By default, this is the leftmost bucket in a view.
type: integer
done_bucket_id:
description: If tasks are moved to the done bucket, they are marked as done.
If they are marked as done individually, they are moved into the done bucket.
type: integer
filter:
description: The filter query to match tasks by. Check out https://vikunja.io/docs/filters
for a full explanation.
type: string
id:
description: The unique numeric id of this view
type: integer
position:
description: The position of this view in the list. The list of all views
will be sorted by this parameter.
type: number
project_id:
description: The project this view belongs to
type: integer
title:
description: The title of this view
type: string
updated:
description: A timestamp when this view was updated. You cannot change this
value.
type: string
view_kind:
allOf:
- $ref: '#/definitions/models.ProjectViewKind'
description: The kind of this view. Can be `list`, `gantt`, `table` or `kanban`.
type: object
models.ProjectViewBucketConfiguration:
properties:
filter:
type: string
title:
type: string
type: object
models.ProjectViewKind:
enum:
- 0
- 1
- 2
- 3
type: integer
x-enum-varnames:
- ProjectViewKindList
- ProjectViewKindGantt
- ProjectViewKindTable
- ProjectViewKindKanban
models.Reaction:
properties:
created:
description: A timestamp when this reaction was created. You cannot change
this value.
type: string
user:
allOf:
- $ref: '#/definitions/user.User'
description: The user who reacted
value:
description: The actual reaction. This can be any valid utf character or text,
up to a length of 20.
type: string
type: object
models.ReactionMap:
additionalProperties:
items:
$ref: '#/definitions/user.User'
type: array
type: object
models.RelatedTaskMap:
additionalProperties:
items:
$ref: '#/definitions/models.Task'
type: array
type: object
models.RelationKind:
enum:
- unknown
- subtask
- parenttask
- related
- duplicateof
- duplicates
- blocking
- blocked
- precedes
- follows
- copiedfrom
- copiedto
type: string
x-enum-varnames:
- RelationKindUnknown
- RelationKindSubtask
- RelationKindParenttask
- RelationKindRelated
- RelationKindDuplicateOf
- RelationKindDuplicates
- RelationKindBlocking
- RelationKindBlocked
- RelationKindPreceeds
- RelationKindFollows
- RelationKindCopiedFrom
- RelationKindCopiedTo
models.ReminderRelation:
enum:
- due_date
- start_date
- end_date
type: string
x-enum-varnames:
- ReminderRelationDueDate
- ReminderRelationStartDate
- ReminderRelationEndDate
models.Right:
enum:
- 0
- 1
- 2
type: integer
x-enum-varnames:
- RightRead
- RightWrite
- RightAdmin
models.RouteDetail:
properties:
method:
type: string
path:
type: string
type: object
models.SavedFilter:
properties:
created:
description: A timestamp when this filter was created. You cannot change this
value.
type: string
description:
description: The description of the filter
type: string
filters:
allOf:
- $ref: '#/definitions/models.TaskCollection'
description: The actual filters this filter contains
id:
description: The unique numeric id of this saved filter
type: integer
is_favorite:
description: True if the filter is a favorite. Favorite filters show up in
a separate parent project together with favorite projects.
type: boolean
owner:
allOf:
- $ref: '#/definitions/user.User'
description: The user who owns this filter
title:
description: The title of the filter.
maxLength: 250
minLength: 1
type: string
updated:
description: A timestamp when this filter was last updated. You cannot change
this value.
type: string
type: object
models.SharingType:
enum:
- 0
- 1
- 2
type: integer
x-enum-varnames:
- SharingTypeUnknown
- SharingTypeWithoutPassword
- SharingTypeWithPassword
models.Subscription:
properties:
created:
description: A timestamp when this subscription was created. You cannot change
this value.
type: string
entity:
type: string
entity_id:
description: The id of the entity to subscribe to.
type: integer
id:
description: The numeric ID of the subscription
type: integer
user:
allOf:
- $ref: '#/definitions/user.User'
description: The user who made this subscription
type: object
models.Task:
properties:
assignees:
description: An array of users who are assigned to this task
items:
$ref: '#/definitions/user.User'
type: array
attachments:
description: All attachments this task has
items:
$ref: '#/definitions/models.TaskAttachment'
type: array
bucket_id:
2024-03-15 22:19:26 +01:00
description: |-
The bucket id. Will only be populated when the task is accessed via a view with buckets.
Can be used to move a task between buckets. In that case, the new bucket must be in the same view as the old one.
type: integer
cover_image_attachment_id:
description: If this task has a cover image, the field will return the id
of the attachment that is the cover image.
type: integer
created:
description: A timestamp when this task was created. You cannot change this
value.
type: string
created_by:
allOf:
- $ref: '#/definitions/user.User'
description: The user who initially created the task.
description:
description: The task description.
type: string
done:
description: Whether a task is done or not.
type: boolean
done_at:
description: The time when a task was marked as done.
type: string
due_date:
description: The time when the task is due.
type: string
end_date:
description: When this task ends.
type: string
hex_color:
description: The task color in hex
2023-10-24 14:38:04 +00:00
maxLength: 7
type: string
id:
description: The unique, numeric id of this task.
type: integer
identifier:
description: The task identifier, based on the project identifier and the
task's index
type: string
index:
description: The task index, calculated per project
type: integer
is_favorite:
description: True if a task is a favorite task. Favorite tasks show up in
a separate "Important" project. This value depends on the user making the
call to the api.
type: boolean
labels:
description: An array of labels which are associated with this task.
items:
$ref: '#/definitions/models.Label'
type: array
percent_done:
description: Determines how far a task is left from being done
type: number
position:
description: |-
The position of the task - any task project can be sorted as usual by this parameter.
2024-03-15 22:19:26 +01:00
When accessing tasks via views with buckets, this is primarily used to sort them based on a range.
Positions are always saved per view. They will automatically be set if you request the tasks through a view
endpoint, otherwise they will always be 0. To update them, take a look at the Task Position endpoint.
type: number
priority:
description: The task priority. Can be anything you want, it is possible to
sort by this later.
type: integer
project_id:
description: The project this task belongs to.
type: integer
2024-03-12 19:47:16 +00:00
reactions:
allOf:
- $ref: '#/definitions/models.ReactionMap'
description: Reactions on that task.
related_tasks:
allOf:
- $ref: '#/definitions/models.RelatedTaskMap'
description: All related tasks, grouped by their relation kind
reminders:
description: An array of reminders that are associated with this task.
items:
$ref: '#/definitions/models.TaskReminder'
type: array
repeat_after:
description: An amount in seconds this task repeats itself. If this is set,
when marking the task as done, it will mark itself as "undone" and then
increase all remindes and the due date by its amount.
type: integer
repeat_mode:
allOf:
- $ref: '#/definitions/models.TaskRepeatMode'
description: 'Can have three possible values which will trigger when the task
is marked as done: 0 = repeats after the amount specified in repeat_after,
1 = repeats all dates each months (ignoring repeat_after), 3 = repeats from
the current date rather than the last set date.'
start_date:
description: When this task starts.
type: string
subscription:
allOf:
- $ref: '#/definitions/models.Subscription'
description: |-
The subscription status for the user reading this task. You can only read this property, use the subscription endpoints to modify it.
Will only returned when retrieving one task.
title:
description: The task text. This is what you'll see in the project.
minLength: 1
type: string
updated:
description: A timestamp when this task was last updated. You cannot change
this value.
type: string
type: object
models.TaskAssginee:
properties:
created:
type: string
user_id:
type: integer
type: object
models.TaskAttachment:
properties:
created:
type: string
created_by:
$ref: '#/definitions/user.User'
file:
$ref: '#/definitions/files.File'
id:
type: integer
task_id:
type: integer
type: object
models.TaskCollection:
properties:
2024-03-09 18:36:25 +01:00
filter:
2024-03-11 16:41:16 +00:00
description: The filter query to match tasks by. Check out https://vikunja.io/docs/filters
2024-03-15 22:19:26 +01:00
for a full explanation.
type: string
filter_include_nulls:
description: If set to true, the result will also include null values
type: boolean
order_by:
description: The query parameter to order the items by. This can be either
asc or desc, with asc being the default.
items:
type: string
type: array
sort_by:
description: The query parameter to sort by. This is for ex. done, priority,
etc.
items:
type: string
type: array
type: object
models.TaskComment:
properties:
author:
$ref: '#/definitions/user.User'
comment:
type: string
created:
type: string
id:
type: integer
2024-03-12 19:47:16 +00:00
reactions:
$ref: '#/definitions/models.ReactionMap'
updated:
type: string
type: object
2024-03-15 22:19:26 +01:00
models.TaskPosition:
properties:
position:
description: |-
The position of the task - any task project can be sorted as usual by this parameter.
When accessing tasks via kanban buckets, this is primarily used to sort them based on a range
We're using a float64 here to make it possible to put any task within any two other tasks (by changing the number).
You would calculate the new position between two tasks with something like task3.position = (task2.position - task1.position) / 2.
A 64-Bit float leaves plenty of room to initially give tasks a position with 2^16 difference to the previous task
which also leaves a lot of room for rearranging and sorting later.
Positions are always saved per view. They will automatically be set if you request the tasks through a view
endpoint, otherwise they will always be 0. To update them, take a look at the Task Position endpoint.
type: number
project_view_id:
description: The project view this task is related to
type: integer
task_id:
description: The ID of the task this position is for
type: integer
type: object
models.TaskRelation:
properties:
created:
description: A timestamp when this label was created. You cannot change this
value.
type: string
created_by:
allOf:
- $ref: '#/definitions/user.User'
description: The user who created this relation
other_task_id:
description: The ID of the other task, the task which is being related.
type: integer
relation_kind:
allOf:
- $ref: '#/definitions/models.RelationKind'
description: The kind of the relation.
task_id:
description: The ID of the "base" task, the task which has a relation to another.
type: integer
type: object
models.TaskReminder:
properties:
relative_period:
description: 'A period in seconds relative to another date argument. Negative
values mean the reminder triggers before the date. Default: 0, tiggers when
RelativeTo is due.'
type: integer
relative_to:
allOf:
- $ref: '#/definitions/models.ReminderRelation'
description: The name of the date field to which the relative period refers
to.
reminder:
description: The absolute time when the user wants to be reminded of the task.
type: string
type: object
models.TaskRepeatMode:
enum:
- 0
- 1
- 2
type: integer
x-enum-varnames:
- TaskRepeatModeDefault
- TaskRepeatModeMonth
- TaskRepeatModeFromCurrentDate
models.Team:
properties:
created:
description: A timestamp when this relation was created. You cannot change
this value.
type: string
created_by:
allOf:
- $ref: '#/definitions/user.User'
description: The user who created this team.
description:
description: The team's description.
type: string
id:
description: The unique, numeric id of this team.
type: integer
include_public:
description: Query parameter controlling whether to include public projects
or not
type: boolean
is_public:
description: Defines wether the team should be publicly discoverable when
sharing a project
type: boolean
members:
description: An array of all members in this team.
items:
$ref: '#/definitions/models.TeamUser'
type: array
name:
description: The name of this team.
maxLength: 250
minLength: 1
type: string
oidc_id:
description: The team's oidc id delivered by the oidc provider
maxLength: 250
type: string
updated:
description: A timestamp when this relation was last updated. You cannot change
this value.
type: string
type: object
models.TeamMember:
properties:
admin:
description: Whether or not the member is an admin of the team. See the docs
for more about what a team admin can do
type: boolean
created:
description: A timestamp when this relation was created. You cannot change
this value.
type: string
id:
description: The unique, numeric id of this team member relation.
type: integer
username:
description: The username of the member. We use this to prevent automated
user id entering.
type: string
type: object
models.TeamProject:
properties:
created:
description: A timestamp when this relation was created. You cannot change
this value.
type: string
id:
description: The unique, numeric id of this project <-> team relation.
type: integer
right:
allOf:
- $ref: '#/definitions/models.Right'
default: 0
description: The right this team has. 0 = Read only, 1 = Read & Write, 2 =
Admin. See the docs for more details.
maximum: 2
team_id:
description: The team id.
type: integer
updated:
description: A timestamp when this relation was last updated. You cannot change
this value.
type: string
type: object
models.TeamUser:
properties:
admin:
2024-03-02 14:50:56 +00:00
description: Whether the member is an admin of the team. See the docs for
more about what a team admin can do
type: boolean
created:
description: A timestamp when this task was created. You cannot change this
value.
type: string
email:
description: The user's email address.
maxLength: 250
type: string
id:
description: The unique, numeric id of this user.
type: integer
name:
description: The full name of the user.
type: string
updated:
description: A timestamp wh