{ "components": { "responses": { "BadRequestResponse": { "content": { "application/json": { "example": { "error": { "code": "bad-request", "message": "Bad request.", "status": 400 } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Bad request." }, "ServerErrorResponse": { "content": { "application/json": { "example": { "error": { "code": "server-error", "message": "Server error.", "status": 500 } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Server error." }, "ServiceUnavailableResponse": { "content": { "application/json": { "example": { "error": { "code": "service-unavailable", "message": "Service unavailable.", "status": 503 } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Service unavailable." }, "UnauthorizedResponse": { "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "Unauthorized.", "status": 401 } }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Unauthorized." } }, "schemas": { "ApiError": { "additionalProperties": false, "description": "Standard Umami API error response.", "properties": { "error": { "additionalProperties": {}, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "message", "code", "status" ], "type": "object" } }, "required": [ "error" ], "type": "object" }, "CreateWebsiteRequest": { "properties": { "domain": { "maxLength": 500, "pattern": "^(localhost(:[1-9]\\d{0,4})?|((?=[a-z0-9-_]{1,63}\\.)(xn--)?[a-z0-9-_]+(-[a-z0-9-_]+)*\\.)+(xn--)?[a-z0-9-_]{2,63})$", "type": "string" }, "id": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] }, "name": { "maxLength": 100, "minLength": 1, "type": "string" }, "shareId": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ] }, "teamId": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "domain" ], "type": "object" }, "LoginRequest": { "properties": { "password": { "description": "Umami password.", "type": "string" }, "username": { "description": "Umami username.", "type": "string" } }, "required": [ "username", "password" ], "type": "object" }, "LoginResponse": { "anyOf": [ { "additionalProperties": false, "properties": { "partialToken": { "type": "string" }, "requiresTwoFactor": { "const": true, "type": "boolean" } }, "required": [ "requiresTwoFactor", "partialToken" ], "type": "object" }, { "additionalProperties": false, "properties": { "token": { "type": "string" }, "user": { "$ref": "#/components/schemas/LoginUser" } }, "required": [ "token", "user" ], "type": "object" } ] }, "LoginTeam": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "logoUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" } }, "required": [ "id", "name", "logoUrl" ], "type": "object" }, "LoginUser": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "isAdmin": { "type": "boolean" }, "role": { "type": "string" }, "teams": { "items": { "$ref": "#/components/schemas/LoginTeam" }, "type": "array" }, "username": { "type": "string" } }, "required": [ "id", "username", "role", "createdAt", "isAdmin", "teams" ], "type": "object" }, "Ok": { "additionalProperties": false, "description": "Successful operation response.", "properties": { "ok": { "const": true, "type": "boolean" } }, "required": [ "ok" ], "type": "object" }, "ReplayConfig": { "additionalProperties": {}, "properties": { "blockSelector": { "type": "string" }, "heatmapEnabled": { "type": "boolean" }, "heatmapSampleRate": { "maximum": 1, "minimum": 0, "type": "number" }, "maskLevel": { "enum": [ "strict", "moderate" ], "type": "string" }, "maxDuration": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "replayEnabled": { "type": "boolean" }, "sampleRate": { "maximum": 1, "minimum": 0, "type": "number" } }, "type": "object" }, "ReplayConfigInput": { "properties": { "blockSelector": { "type": "string" }, "heatmapEnabled": { "type": "boolean" }, "heatmapSampleRate": { "maximum": 1, "minimum": 0, "type": "number" }, "maskLevel": { "enum": [ "strict", "moderate" ], "type": "string" }, "maxDuration": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "replayEnabled": { "type": "boolean" }, "sampleRate": { "maximum": 1, "minimum": 0, "type": "number" } }, "type": "object" }, "UpdateWebsiteRequest": { "properties": { "domain": { "maxLength": 500, "pattern": "^(localhost(:[1-9]\\d{0,4})?|((?=[a-z0-9-_]{1,63}\\.)(xn--)?[a-z0-9-_]+(-[a-z0-9-_]+)*\\.)+(xn--)?[a-z0-9-_]{2,63})$", "type": "string" }, "name": { "maxLength": 100, "minLength": 1, "type": "string" }, "replayConfig": { "anyOf": [ { "$ref": "#/components/schemas/ReplayConfigInput" }, { "type": "null" } ] }, "shareId": { "anyOf": [ { "maxLength": 50, "type": "string" }, { "type": "null" } ] } }, "type": "object" }, "Website": { "additionalProperties": false, "properties": { "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "createdBy": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] }, "deletedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "name": { "type": "string" }, "recorderEnabled": { "type": "boolean" }, "replayConfig": { "anyOf": [ { "$ref": "#/components/schemas/ReplayConfig" }, { "type": "null" } ] }, "resetAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "shareId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "teamId": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "user": { "$ref": "#/components/schemas/WebsiteUser" }, "userId": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "name", "domain", "resetAt", "userId", "teamId", "createdBy", "createdAt", "updatedAt", "deletedAt", "recorderEnabled", "replayConfig", "shareId" ], "type": "object" }, "WebsitePage": { "additionalProperties": false, "properties": { "count": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "data": { "items": { "$ref": "#/components/schemas/Website" }, "type": "array" }, "orderBy": { "type": "string" }, "page": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" }, "pageSize": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "search": { "type": "string" } }, "required": [ "data", "count", "page", "pageSize" ], "type": "object" }, "WebsiteUser": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "username": { "type": "string" } }, "required": [ "id", "username" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "JWT", "description": "Token returned by POST /api/auth/login.", "scheme": "bearer", "type": "http" }, "shareContext": { "description": "Required context header when authenticating with a share token.", "in": "header", "name": "x-umami-share-context", "type": "apiKey" }, "shareToken": { "description": "Signed token returned by a share endpoint.", "in": "header", "name": "x-umami-share-token", "type": "apiKey" } } }, "externalDocs": { "description": "Umami API documentation", "url": "https://docs.umami.is/docs/api" }, "info": { "description": "REST API for Umami analytics. Self-hosted deployments serve these paths beneath their configured BASE_PATH.", "license": { "identifier": "MIT", "name": "MIT" }, "title": "Umami API", "version": "3.3.0" }, "openapi": "3.1.0", "paths": { "/api/auth/login": { "post": { "description": "Authenticates a self-hosted Umami user. Users with two-factor authentication receive a short-lived partial token instead of a full bearer token.", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } }, "description": "Authenticated successfully." }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Log in", "tags": [ "Authentication" ], "x-umami-audience": "public" } }, "/api/websites": { "get": { "description": "Returns websites owned by the authenticated user.", "operationId": "listWebsites", "parameters": [ { "in": "query", "name": "page", "schema": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" } }, { "in": "query", "name": "pageSize", "schema": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" } }, { "in": "query", "name": "maxResults", "schema": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "type": "integer" } }, { "in": "query", "name": "search", "schema": { "type": "string" } }, { "in": "query", "name": "orderBy", "schema": { "type": "string" } }, { "in": "query", "name": "sortDescending", "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "description": "When present, include websites accessible through owned or managed teams.", "in": "query", "name": "includeTeams", "schema": { "description": "When present, include websites accessible through owned or managed teams.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsitePage" } } }, "description": "A page of websites." }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" } }, "security": [ { "bearerAuth": [] } ], "summary": "List websites", "tags": [ "Websites" ], "x-umami-audience": "public" }, "post": { "operationId": "createWebsite", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebsiteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Website" } } }, "description": "Website created." }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a website", "tags": [ "Websites" ], "x-umami-audience": "public" } }, "/api/websites/{websiteId}": { "delete": { "operationId": "deleteWebsite", "parameters": [ { "description": "Website ID.", "in": "path", "name": "websiteId", "required": true, "schema": { "description": "Website ID.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } }, "description": "Website deleted." }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete a website", "tags": [ "Websites" ], "x-umami-audience": "public" }, "get": { "operationId": "getWebsite", "parameters": [ { "description": "Website ID.", "in": "path", "name": "websiteId", "required": true, "schema": { "description": "Website ID.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Website" }, { "type": "null" } ] } } }, "description": "Website details, or null if it does not exist." }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" } }, "security": [ { "bearerAuth": [] }, { "shareContext": [], "shareToken": [] } ], "summary": "Get a website", "tags": [ "Websites" ], "x-umami-audience": "public" }, "post": { "operationId": "updateWebsite", "parameters": [ { "description": "Website ID.", "in": "path", "name": "websiteId", "required": true, "schema": { "description": "Website ID.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebsiteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Website" } } }, "description": "Website updated." }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/ServerErrorResponse" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update a website", "tags": [ "Websites" ], "x-umami-audience": "public" } } }, "tags": [ { "name": "Authentication" }, { "name": "Websites" } ] }