vikunja/pkg/swagger/swagger.json

9638 lines
355 KiB
JSON
Raw Normal View History

{
"swagger": "2.0",
"info": {
"description": "# Pagination\nEvery endpoint capable of pagination will return two headers:\n* `x-pagination-total-pages`: The total number of available pages for this request\n* `x-pagination-result-count`: The number of items returned for this request.\n# Rights\nAll endpoints which return a single item (project, task, etc.) - no array - will also return a `x-max-right` header with the max right the user has on this item as an int where `0` is `Read Only`, `1` is `Read \u0026 Write` and `2` is `Admin`.\nThis can be used to show or hide ui elements based on the rights the user has.\n# Errors\nAll errors have an error code and a human-readable error message in addition to the http status code. You should always check for the status code in the response, not only the http status code.\nDue to limitations in the swagger library we're using for this document, only one error per http status code is documented here. Make sure to check the [error docs](https://vikunja.io/docs/errors/) in Vikunja's documentation for a full list of available error codes.\n# Authorization\n**JWT-Auth:** Main authorization method, used for most of the requests. Needs `Authorization: Bearer \u003cjwt-token\u003e`-header to authenticate successfully.\n\n**API Token:** You can create scoped API tokens for your user and use the token to make authenticated requests in the context of that user. The token must be provided via an `Authorization: Bearer \u003ctoken\u003e` header, similar to jwt auth. See the documentation for the `api` group to manage token creation and revocation.\n\n**BasicAuth:** Only used when requesting tasks via CalDAV.\n\u003c!-- ReDoc-Inject: \u003csecurity-definitions\u003e --\u003e",
"title": "Vikunja API",
"contact": {
"name": "General Vikunja contact",
"url": "https://vikunja.io/contact/",
"email": "hello@vikunja.io"
},
"license": {
"name": "AGPL-3.0-or-later",
"url": "https://code.vikunja.io/api/src/branch/main/LICENSE"
}
},
"basePath": "/api/v1",
"paths": {
"/auth/openid/{provider}/callback": {
"post": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "After a redirect from the OpenID Connect provider to the frontend has been made with the authentication `code`, this endpoint can be used to obtain a jwt token for that user and thus log them in.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Authenticate a user with OpenID Connect",
"operationId": "get-token-openid",
"parameters": [
{
"description": "The openid callback",
"name": "callback",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/openid.Callback"
}
},
{
"type": "integer",
"description": "The OpenID Connect provider key as returned by the /info endpoint",
"name": "provider",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/auth.Token"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/backgrounds/unsplash/image/{image}": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Get an unsplash image. **Returns json on error.**",
"produces": [
"application/octet-stream"
],
"tags": [
"project"
],
"summary": "Get an unsplash image",
"parameters": [
{
"type": "integer",
"description": "Unsplash Image ID",
"name": "image",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The image",
"schema": {
"type": "file"
}
},
"404": {
"description": "The image does not exist.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/backgrounds/unsplash/image/{image}/thumb": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Get an unsplash thumbnail image. The thumbnail is cropped to a max width of 200px. **Returns json on error.**",
"produces": [
"application/octet-stream"
],
"tags": [
"project"
],
"summary": "Get an unsplash thumbnail image",
"parameters": [
{
"type": "integer",
"description": "Unsplash Image ID",
"name": "image",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The thumbnail",
"schema": {
"type": "file"
}
},
"404": {
"description": "The image does not exist.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/backgrounds/unsplash/search": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Search for a project background from unsplash",
"produces": [
"application/json"
],
"tags": [
"project"
],
"summary": "Search for a background from unsplash",
"parameters": [
{
"type": "string",
"description": "Search backgrounds from unsplash with this search term.",
"name": "s",
"in": "query"
},
{
"type": "integer",
"description": "The page number. Used for pagination. If not provided, the first page of results is returned.",
"name": "p",
"in": "query"
}
],
"responses": {
"200": {
"description": "An array with photos",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/background.Image"
}
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/filters": {
"put": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Creates a new saved filter",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"filter"
],
"summary": "Creates a new saved filter",
"responses": {
"201": {
"description": "The Saved Filter",
"schema": {
"$ref": "#/definitions/models.SavedFilter"
}
},
"403": {
"description": "The user does not have access to that saved filter.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/filters/{id}": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns a saved filter by its ID.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"filter"
],
"summary": "Gets one saved filter",
"parameters": [
{
"type": "integer",
"description": "Filter ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The Saved Filter",
"schema": {
"$ref": "#/definitions/models.SavedFilter"
}
},
"403": {
"description": "The user does not have access to that saved filter.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"post": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Updates a saved filter by its ID.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"filter"
],
"summary": "Updates a saved filter",
"parameters": [
{
"type": "integer",
"description": "Filter ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The Saved Filter",
"schema": {
"$ref": "#/definitions/models.SavedFilter"
}
},
"403": {
"description": "The user does not have access to that saved filter.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"404": {
"description": "The saved filter does not exist.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"delete": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Removes a saved filter by its ID.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"filter"
],
"summary": "Removes a saved filter",
"parameters": [
{
"type": "integer",
"description": "Filter ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The Saved Filter",
"schema": {
"$ref": "#/definitions/models.SavedFilter"
}
},
"403": {
"description": "The user does not have access to that saved filter.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"404": {
"description": "The saved filter does not exist.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/info": {
"get": {
"description": "Returns the version, frontendurl, motd and various settings of Vikunja",
"produces": [
"application/json"
],
"tags": [
"service"
],
"summary": "Info",
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/v1.vikunjaInfos"
}
}
}
}
},
"/labels": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns all labels which are either created by the user or associated with a task the user has at least read-access to.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"labels"
],
"summary": "Get all labels a user has access to",
"parameters": [
{
"type": "integer",
"description": "The page number. Used for pagination. If not provided, the first page of results is returned.",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "The maximum number of items per page. Note this parameter is limited by the configured maximum of items per page.",
"name": "per_page",
"in": "query"
},
{
"type": "string",
"description": "Search labels by label text.",
"name": "s",
"in": "query"
}
],
"responses": {
"200": {
"description": "The labels",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/models.Label"
}
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"put": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Creates a new label.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"labels"
],
"summary": "Create a label",
"parameters": [
{
"description": "The label object",
"name": "label",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.Label"
}
}
],
"responses": {
"201": {
"description": "The created label object.",
"schema": {
"$ref": "#/definitions/models.Label"
}
},
"400": {
"description": "Invalid label object provided.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/labels/{id}": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns one label by its ID.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"labels"
],
"summary": "Gets one label",
"parameters": [
{
"type": "integer",
"description": "Label ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The label",
"schema": {
"$ref": "#/definitions/models.Label"
}
},
"403": {
"description": "The user does not have access to the label",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"404": {
"description": "Label not found",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"put": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Update an existing label. The user needs to be the creator of the label to be able to do this.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"labels"
],
"summary": "Update a label",
"parameters": [
{
"type": "integer",
"description": "Label ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "The label object",
"name": "label",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.Label"
}
}
],
"responses": {
"200": {
"description": "The created label object.",
"schema": {
"$ref": "#/definitions/models.Label"
}
},
"400": {
"description": "Invalid label object provided.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"403": {
"description": "Not allowed to update the label.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"404": {
"description": "Label not found.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"delete": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Delete an existing label. The user needs to be the creator of the label to be able to do this.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"labels"
],
"summary": "Delete a label",
"parameters": [
{
"type": "integer",
"description": "Label ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The label was successfully deleted.",
"schema": {
"$ref": "#/definitions/models.Label"
}
},
"403": {
"description": "Not allowed to delete the label.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"404": {
"description": "Label not found.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/login": {
"post": {
"description": "Logs a user in. Returns a JWT-Token to authenticate further requests.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"auth"
],
"summary": "Login",
"parameters": [
{
"description": "The login credentials",
"name": "credentials",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/user.Login"
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/auth.Token"
}
},
"400": {
"description": "Invalid user password model.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"403": {
"description": "Invalid username or password.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"412": {
"description": "Invalid totp passcode.",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/microsoft-todo/auth": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns the auth url where the user needs to get its auth code. This code can then be used to migrate everything from Microsoft Todo to Vikunja.",
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Get the auth url from Microsoft Todo",
"responses": {
"200": {
"description": "The auth url.",
"schema": {
"$ref": "#/definitions/handler.AuthURL"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/microsoft-todo/migrate": {
"post": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Migrates all tasklinsts, tasks, notes and reminders from Microsoft Todo to Vikunja.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Migrate all projects, tasks etc. from Microsoft Todo",
"parameters": [
{
"description": "The auth token previously obtained from the auth url. See the docs for /migration/microsoft-todo/auth.",
"name": "migrationCode",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/microsofttodo.Migration"
}
}
],
"responses": {
"200": {
"description": "A message telling you everything was migrated successfully.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/microsoft-todo/status": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns if the current user already did the migation or not. This is useful to show a confirmation message in the frontend if the user is trying to do the same migration again.",
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Get migration status",
"responses": {
"200": {
"description": "The migration status",
"schema": {
"$ref": "#/definitions/migration.Status"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/ticktick/migrate": {
"post": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Imports all projects, tasks, notes, reminders, subtasks and files from a TickTick backup export into Vikunja.",
"consumes": [
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Import all projects, tasks etc. from a TickTick backup export",
"parameters": [
{
"type": "string",
"description": "The TickTick backup csv file.",
"name": "import",
"in": "formData",
"required": true
}
],
"responses": {
"200": {
"description": "A message telling you everything was migrated successfully.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/ticktick/status": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns if the current user already did the migation or not. This is useful to show a confirmation message in the frontend if the user is trying to do the same migration again.",
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Get migration status",
"responses": {
"200": {
"description": "The migration status",
"schema": {
"$ref": "#/definitions/migration.Status"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/todoist/auth": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns the auth url where the user needs to get its auth code. This code can then be used to migrate everything from todoist to Vikunja.",
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Get the auth url from todoist",
"responses": {
"200": {
"description": "The auth url.",
"schema": {
"$ref": "#/definitions/handler.AuthURL"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/todoist/migrate": {
"post": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Migrates all projects, tasks, notes, reminders, subtasks and files from todoist to vikunja.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Migrate all lists, tasks etc. from todoist",
"parameters": [
{
"description": "The auth code previously obtained from the auth url. See the docs for /migration/todoist/auth.",
"name": "migrationCode",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/todoist.Migration"
}
}
],
"responses": {
"200": {
"description": "A message telling you everything was migrated successfully.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/todoist/status": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns if the current user already did the migation or not. This is useful to show a confirmation message in the frontend if the user is trying to do the same migration again.",
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Get migration status",
"responses": {
"200": {
"description": "The migration status",
"schema": {
"$ref": "#/definitions/migration.Status"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/trello/auth": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns the auth url where the user needs to get its auth code. This code can then be used to migrate everything from trello to Vikunja.",
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Get the auth url from trello",
"responses": {
"200": {
"description": "The auth url.",
"schema": {
"$ref": "#/definitions/handler.AuthURL"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/trello/migrate": {
"post": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Migrates all projects, tasks, notes, reminders, subtasks and files from trello to vikunja.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Migrate all projects, tasks etc. from trello",
"parameters": [
{
"description": "The auth token previously obtained from the auth url. See the docs for /migration/trello/auth.",
"name": "migrationCode",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/trello.Migration"
}
}
],
"responses": {
"200": {
"description": "A message telling you everything was migrated successfully.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/trello/status": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Returns if the current user already did the migation or not. This is useful to show a confirmation message in the frontend if the user is trying to do the same migration again.",
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Get migration status",
"responses": {
"200": {
"description": "The migration status",
"schema": {
"$ref": "#/definitions/migration.Status"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/migration/vikunja-file/migrate": {
"post": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Imports all projects, tasks, notes, reminders, subtasks and files from a Vikunjda data export into Vikunja.",
"consumes": [
"application/x-www-form-urlencoded"
],
"produces": [
"application/json"
],
"tags": [
"migration"
],
"summary": "Import all projects, tasks etc. from a Vikunja data export",
"parameters": [
{
"type": "string",
"description": "The Vikunja export zip file.",
"name": "import",
"in": "formData",
"required": true
}
],
"responses": {
"200": {
"description": "A message telling you everything was migrated successfully.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"