{ "components": { "responses": {}, "schemas": { "AddInput": { "additionalProperties": false, "properties": { "apikeys": { "description": "One or more 40 character hex API keys.", "items": { "$ref": "#/components/schemas/ApiKey" }, "maxItems": 1024, "minItems": 1, "type": "array" }, "application": { "description": "Up to 256 bytes. Used as a grouping key in the UI.", "example": "deploy.sh", "maxLength": 256, "minLength": 1, "type": "string" }, "description": { "description": "Up to 10000 bytes.", "example": "web @ a17f2c · 38s · green", "maxLength": 10000, "nullable": true, "type": "string" }, "event": { "description": "Headline for a notification, up to 1024 bytes.", "example": "shipped", "maxLength": 1024, "minLength": 1, "type": "string" }, "priority": { "$ref": "#/components/schemas/Priority" }, "providerkey": { "$ref": "#/components/schemas/ProviderKey" }, "url": { "$ref": "#/components/schemas/Url" } }, "required": [ "apikeys", "application", "event" ], "title": "AddInput", "type": "object" }, "AddOutput": { "example": { "notifications": [ { "apikey": "0123456789abcdef0123456789abcdef0123aaaa", "status": "sent" }, { "apikey": "0123456789abcdef0123456789abcdef0123bbbb", "error": "invalid_api_key", "status": "error" } ] }, "properties": { "notifications": { "description": "One entry per input apikey, in request order.", "items": { "$ref": "#/components/schemas/AddResult" }, "type": "array" } }, "required": [ "notifications" ], "title": "AddOutput", "type": "object" }, "AddResult": { "properties": { "apikey": { "$ref": "#/components/schemas/ApiKey" }, "error": { "description": "Only present if `status` is `error`.", "enum": [ "invalid_api_key", "server_error" ], "type": "string" }, "status": { "description": "Whether delivery to the key was successful.", "enum": [ "sent", "error" ], "type": "string" } }, "required": [ "apikey", "status" ], "title": "AddResult", "type": "object" }, "ApiKey": { "description": "The key provided in the request.", "example": "abcdef0123456789abcdef0123456789abcdef01", "pattern": "^[0-9a-f]{40}$", "title": "ApiKey", "type": "string" }, "InvalidParam": { "properties": { "name": { "description": "Dotted field name (e.g. `apikeys.7`).", "example": "apikeys.7", "type": "string" }, "pointer": { "description": "RFC 6901 JSON Pointer (e.g. '/apikeys/7').", "example": "/apikeys/7", "type": "string" }, "reason": { "description": "Human-readable reason for the field error.", "example": "must be a 40-character hex string", "type": "string" } }, "required": [ "name", "pointer", "reason" ], "title": "InvalidParam", "type": "object" }, "Priority": { "default": "normal", "description": "Defaults to `normal`", "enum": [ "very_low", "moderate", "normal", "high", "emergency" ], "example": "high", "title": "Priority", "type": "string" }, "Problem": { "additionalProperties": true, "example": { "code": "invalid_parameters", "detail": "Request body failed validation.", "instance": "/2/add", "invalid_params": [ { "name": "priority", "pointer": "/priority", "reason": "must be one of: low, moderate, normal, high, emergency" } ], "status": 400, "title": "Validation failed." }, "properties": { "code": { "description": "The reason for the failure.", "enum": [ "access_denied", "authorization_pending", "destination_limit_reached", "expired_token", "interactive_login_required", "invalid_api_key", "invalid_credentials", "invalid_grant", "invalid_idempotency_key", "invalid_parameters", "invalid_provider_key", "invalid_token", "not_found", "pause_not_clearable", "server_error", "throttled", "unsupported_media_type" ], "type": "string" }, "detail": { "description": "Human-readable explanation of the error.", "type": "string" }, "instance": { "description": "Request path which caused the error.", "type": "string" }, "invalid_params": { "description": "Per-field validation when `code` is `invalid_parameters`.", "items": { "$ref": "#/components/schemas/InvalidParam" }, "type": "array" }, "status": { "description": "The HTTP status code.", "type": "integer" }, "title": { "description": "Human-readable representation of the `code`.", "type": "string" } }, "required": [ "code", "title", "status", "detail", "instance" ], "title": "Problem", "type": "object" }, "ProviderKey": { "description": "Your provider key, if you are using one.", "example": "fedcba9876543210fedcba9876543210fedcba98", "pattern": "^[0-9a-f]{40}$", "title": "ProviderKey", "type": "string" }, "RetrieveApikeyInput": { "additionalProperties": false, "properties": { "providerkey": { "$ref": "#/components/schemas/ProviderKey" }, "token": { "description": "The token created from the previous request.", "example": "0123456789abcdef0123456789abcdef01234567", "pattern": "^[0-9a-f]{40}$", "type": "string" } }, "required": [ "providerkey", "token" ], "title": "RetrieveApikeyInput", "type": "object" }, "RetrieveApikeyOutput": { "properties": { "apikey": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "apikey" ], "title": "RetrieveApikeyOutput", "type": "object" }, "RetrieveTokenInput": { "additionalProperties": false, "properties": { "providerkey": { "$ref": "#/components/schemas/ProviderKey" } }, "required": [ "providerkey" ], "title": "RetrieveTokenInput", "type": "object" }, "RetrieveTokenOutput": { "properties": { "approval_url": { "$ref": "#/components/schemas/Url" }, "token": { "description": "The token to use for the next step.", "example": "0123456789abcdef0123456789abcdef01234567", "pattern": "^[0-9a-f]{40}$", "type": "string" } }, "required": [ "token", "approval_url" ], "title": "RetrieveTokenOutput", "type": "object" }, "Url": { "description": "A URL field (e.g. `https://...`)", "example": "https://github.com/zacwest/prowl/pull/42", "format": "uri", "maxLength": 512, "title": "Url", "type": "string" }, "VerifyInput": { "additionalProperties": false, "properties": { "apikey": { "$ref": "#/components/schemas/ApiKey" }, "providerkey": { "$ref": "#/components/schemas/ProviderKey" } }, "required": [ "apikey" ], "title": "VerifyInput", "type": "object" }, "VerifyOutput": { "properties": { "valid": { "description": "Whether the key was valid.", "type": "boolean" } }, "required": [ "valid" ], "title": "VerifyOutput", "type": "object" } }, "securitySchemes": {} }, "info": { "contact": { "name": "Prowl", "url": "https://www.prowlapp.com/support" }, "description": "Public API for Prowl. Two surface versions: `/1/*` for the old, frozen legacy API (also aliased at `/publicapi`). `/2/*` for the new, modern JSON format.", "license": { "name": "Proprietary", "url": "https://www.prowlapp.com/privacy" }, "title": "Prowl Public API (V2)", "version": "2.1.0" }, "openapi": "3.0.3", "paths": { "/add": { "post": { "callbacks": {}, "description": "Sends a notification to one or more API keys.", "operationId": "add", "parameters": [ { "description": "Printable ASCII only. Generate a random value, reuse it on retries to prevent duplicate notifications.", "in": "header", "name": "idempotency-key", "required": false, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[!-~]+$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOutput" } } }, "description": "Notification added" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Validation failed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Authentication failed" }, "415": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid content-type" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Throttled" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Server error" } }, "summary": "Add and send a notification", "tags": [ "Notifications" ] } }, "/retrieve/apikey": { "post": { "callbacks": {}, "description": "Call this after the user approves the retrieve request.", "operationId": "retrieveApikey", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveApikeyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveApikeyOutput" } } }, "description": "API key created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Validation failed or not approved" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Unknown providerkey" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Throttled" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Server error" } }, "summary": "Exchange a retrieve token for an API key", "tags": [ "Apikeys" ] } }, "/retrieve/token": { "post": { "callbacks": {}, "description": "Create a token and get the callback URL, then send the user to the URL to approve.", "operationId": "retrieveToken", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveTokenInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetrieveTokenOutput" } } }, "description": "Token created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Validation failed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Unknown providerkey" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Throttled" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Server error" } }, "summary": "Mint a token to retrieve an API key", "tags": [ "Tokens" ] } }, "/verify": { "post": { "callbacks": {}, "description": "Verify whether an API key is valid. Use this when the user is inputting it, you don't need to issue it before adding a notification.", "operationId": "verify", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyOutput" } } }, "description": "Valid key" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Validation failed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid key" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Throttled" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Server error" } }, "summary": "Verify an API key", "tags": [ "Apikeys" ] } } }, "security": [], "servers": [ { "url": "https://api.prowlapp.com/{version}", "variables": { "version": { "default": "2", "description": "API major version (path segment)." } } } ], "tags": [ { "description": "Send notifications.", "name": "Notifications" }, { "description": "Verify or redeem an API key.", "name": "Apikeys" }, { "description": "Mint a token to retrieve an API key.", "name": "Tokens" }, { "description": "Notification destinations.", "name": "Destinations" }, { "description": "The authenticated user's account and resolved plan.", "name": "Account" }, { "description": "Billing and subscription hand-off.", "name": "Billing" } ] }