{ "openapi": "3.0.4", "info": { "title": "MetricsPocket Public API", "description": "List and create habits, read and set their daily values, pull stats, and add dashboard charts. Authenticate by sending your key in the X-API-KEY header (or as a Bearer token).", "version": "v1" }, "paths": { "/api/v1/account": { "get": { "tags": [ "PublicAccount" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAccountModel" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/charts": { "get": { "tags": [ "PublicCharts" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicChartModel" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "PublicCharts" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublicChartRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreatePublicChartRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreatePublicChartRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicChartModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/entries": { "get": { "tags": [ "PublicEntries" ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicHabitEntriesGroupModel" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/habits": { "get": { "tags": [ "PublicHabits" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicHabitModel" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "post": { "tags": [ "PublicHabits" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePublicHabitRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreatePublicHabitRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreatePublicHabitRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicHabitModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/habits/{habitId}/entries": { "get": { "tags": [ "PublicHabits" ], "parameters": [ { "name": "habitId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicHabitEntryModel" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/habits/{habitId}/entries/{date}": { "put": { "tags": [ "PublicHabits" ], "parameters": [ { "name": "habitId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetEntryRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SetEntryRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/SetEntryRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicHabitEntryModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } }, "delete": { "tags": [ "PublicHabits" ], "parameters": [ { "name": "habitId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/sections": { "get": { "tags": [ "PublicSections" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicSectionModel" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "/api/v1/stats": { "get": { "tags": [ "PublicStats" ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStatsModel" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "CreatePublicChartRequest": { "required": [ "habitIds", "name", "type" ], "type": "object", "properties": { "name": { "maxLength": 256, "minLength": 1, "type": "string" }, "type": { "minLength": 1, "type": "string" }, "habitIds": { "minItems": 1, "type": "array", "items": { "type": "string", "format": "uuid" } }, "days": { "maximum": 3650, "minimum": -1, "type": "integer", "format": "int32" }, "candleBottomOffset": { "maximum": 7, "minimum": -7, "type": "integer", "format": "int32" }, "candleTopOffset": { "maximum": 7, "minimum": -7, "type": "integer", "format": "int32" } }, "additionalProperties": false }, "CreatePublicHabitRequest": { "required": [ "name", "type" ], "type": "object", "properties": { "name": { "maxLength": 256, "minLength": 1, "type": "string" }, "description": { "maxLength": 1024, "type": "string", "nullable": true }, "type": { "minLength": 1, "type": "string" }, "color": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "nullable": true }, "unit": { "maxLength": 50, "pattern": "^[\\w\\s\\(\\)\\/\\.\\-]+$", "type": "string", "nullable": true }, "target": { "type": "number", "format": "double", "nullable": true }, "timeTarget": { "type": "string", "nullable": true }, "goalOperator": { "type": "string", "nullable": true }, "isMultiSelect": { "type": "boolean" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/CreatePublicSelectOption" }, "nullable": true }, "excludedDays": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true }, "sectionId": { "type": "string", "format": "uuid", "nullable": true } }, "additionalProperties": false }, "CreatePublicSelectOption": { "required": [ "label" ], "type": "object", "properties": { "label": { "maxLength": 256, "minLength": 1, "type": "string" }, "color": { "pattern": "^#[0-9A-Fa-f]{6}$", "type": "string", "nullable": true } }, "additionalProperties": false }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": { } }, "PublicAccountModel": { "type": "object", "properties": { "timezone": { "type": "string", "nullable": true }, "weekStartDay": { "type": "string", "nullable": true }, "timeFormat": { "type": "string", "nullable": true }, "today": { "type": "string", "format": "date" }, "serverTimeUtc": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "PublicChartModel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "habitIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true }, "days": { "type": "integer", "format": "int32" }, "isDefault": { "type": "boolean" }, "candleBottomOffset": { "type": "integer", "format": "int32" }, "candleTopOffset": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "PublicHabitEntriesGroupModel": { "type": "object", "properties": { "habitId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "unit": { "type": "string", "nullable": true }, "target": { "type": "number", "format": "double", "nullable": true }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/PublicHabitEntryModel" }, "nullable": true } }, "additionalProperties": false }, "PublicHabitEntryModel": { "type": "object", "properties": { "habitId": { "type": "string", "format": "uuid" }, "date": { "type": "string", "format": "date" }, "status": { "type": "string", "nullable": true }, "value": { "type": "number", "format": "double", "nullable": true }, "time": { "type": "string", "nullable": true }, "optionIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "additionalProperties": false }, "PublicHabitModel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true }, "unit": { "type": "string", "nullable": true }, "target": { "type": "number", "format": "double", "nullable": true }, "timeTarget": { "type": "string", "nullable": true }, "goalOperator": { "type": "string", "nullable": true }, "isMultiSelect": { "type": "boolean" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/PublicSelectOptionModel" }, "nullable": true }, "excludedDays": { "type": "array", "items": { "type": "integer", "format": "int32" }, "nullable": true }, "currentStreak": { "type": "integer", "format": "int32" }, "bestStreak": { "type": "integer", "format": "int32" }, "section": { "$ref": "#/components/schemas/PublicSectionModel" }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "PublicHabitStatsModel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true }, "unit": { "type": "string", "nullable": true }, "target": { "type": "number", "format": "double", "nullable": true }, "currentStreak": { "type": "integer", "format": "int32" }, "bestStreak": { "type": "integer", "format": "int32" }, "trackedDays": { "type": "integer", "format": "int32" }, "totalDays": { "type": "integer", "format": "int32" }, "rate": { "type": "integer", "format": "int32" }, "average": { "type": "number", "format": "double", "nullable": true }, "dailyValues": { "type": "object", "additionalProperties": { "type": "number", "format": "double" }, "nullable": true }, "weeklyRates": { "type": "array", "items": { "$ref": "#/components/schemas/PublicWeeklyPointModel" }, "nullable": true } }, "additionalProperties": false }, "PublicSectionModel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PublicSelectOptionModel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string", "nullable": true }, "color": { "type": "string", "nullable": true } }, "additionalProperties": false }, "PublicStatsModel": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "totalDone": { "type": "integer", "format": "int32" }, "totalPossible": { "type": "integer", "format": "int32" }, "overallRate": { "type": "integer", "format": "int32" }, "bestStreak": { "type": "integer", "format": "int32" }, "bestStreakHabitName": { "type": "string", "nullable": true }, "perfectDays": { "type": "integer", "format": "int32" }, "weeklyPerfectDays": { "type": "array", "items": { "$ref": "#/components/schemas/PublicWeeklyPointModel" }, "nullable": true }, "habits": { "type": "array", "items": { "$ref": "#/components/schemas/PublicHabitStatsModel" }, "nullable": true } }, "additionalProperties": false }, "PublicWeeklyPointModel": { "type": "object", "properties": { "week": { "type": "string", "nullable": true }, "value": { "type": "number", "format": "double" } }, "additionalProperties": false }, "SetEntryRequest": { "type": "object", "properties": { "status": { "type": "string", "nullable": true }, "value": { "type": "number", "format": "double", "nullable": true }, "time": { "type": "string", "nullable": true }, "optionIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "description": "Your Public API key, e.g. mp_live_…", "name": "X-API-KEY", "in": "header" } } }, "security": [ { "ApiKey": [ ] } ], "tags": [ { "name": "PublicAccount" }, { "name": "PublicCharts" }, { "name": "PublicEntries" }, { "name": "PublicHabits" }, { "name": "PublicSections" }, { "name": "PublicStats" } ] }