{
  "openapi": "3.0.3",
  "info": {
    "title": "DockDart Product Information API",
    "version": "1.0.0",
    "description": "Free, public, read-only product and release information. No API key or account is required. These endpoints cannot control a Mac, access user data, activate a license, or make a purchase. Deprecation policy: v1 is not deprecated. Before removing a stable version, publish at least 90 days of notice, a migration guide, RFC 9745 Deprecation and RFC 8594 Sunset headers.",
    "x-deprecation-policy": "https://www.dockdart.com/api#compatibility",
    "contact": {
      "name": "DockDart support",
      "email": "support@dockdart.com",
      "url": "https://www.dockdart.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://www.dockdart.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "DockDart API documentation and examples",
    "url": "https://www.dockdart.com/api"
  },
  "security": [],
  "tags": [
    {
      "name": "Product",
      "description": "Product facts and app requirements."
    },
    {
      "name": "Release",
      "description": "Current app release and download checksum."
    }
  ],
  "paths": {
    "/api/v1/product": {
      "get": {
        "operationId": "getDockDartProduct",
        "tags": [
          "Product"
        ],
        "summary": "Read DockDart product information",
        "description": "Use this to explain DockDart, check macOS requirements, compare free and Pro terms, or retrieve the official support and download links. The capabilities field describes the native app; it is not an API tool list.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language of localized product text. Omit for English.",
            "schema": {
              "type": "string",
              "enum": [
                "en",
                "zh"
              ],
              "default": "en"
            },
            "example": "en"
          }
        ],
        "responses": {
          "200": {
            "description": "Current public information.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Public product facts; capabilities describe the installed Mac app, not remote API actions.",
                  "additionalProperties": false,
                  "required": [
                    "name",
                    "type",
                    "description",
                    "audience",
                    "capabilities",
                    "requirements",
                    "pricing",
                    "download",
                    "authentication",
                    "apiEndpoints",
                    "integration",
                    "whenToUse",
                    "documentation",
                    "support"
                  ],
                  "properties": {
                    "name": {
                      "type": "string",
                      "description": "Product name."
                    },
                    "type": {
                      "type": "string",
                      "description": "Product category."
                    },
                    "description": {
                      "type": "string",
                      "description": "Product overview in the requested language."
                    },
                    "audience": {
                      "type": "array",
                      "description": "People who can benefit from DockDart.",
                      "items": {
                        "type": "string"
                      }
                    },
                    "capabilities": {
                      "type": "array",
                      "description": "Capabilities of the locally installed Mac app.",
                      "items": {
                        "type": "string"
                      }
                    },
                    "requirements": {
                      "type": "object",
                      "description": "Installation requirements.",
                      "additionalProperties": false,
                      "required": [
                        "operatingSystem",
                        "accountRequired",
                        "permissions"
                      ],
                      "properties": {
                        "operatingSystem": {
                          "type": "string",
                          "description": "Minimum supported operating system."
                        },
                        "accountRequired": {
                          "type": "boolean",
                          "description": "Whether the Mac app requires an account."
                        },
                        "permissions": {
                          "type": "string",
                          "description": "When macOS permissions are requested."
                        }
                      }
                    },
                    "pricing": {
                      "type": "object",
                      "description": "Current public pricing and trial terms.",
                      "additionalProperties": false,
                      "required": [
                        "free",
                        "pro",
                        "trial"
                      ],
                      "properties": {
                        "free": {
                          "type": "string",
                          "description": "Free feature availability."
                        },
                        "pro": {
                          "type": "string",
                          "description": "Pro purchase terms."
                        },
                        "trial": {
                          "type": "string",
                          "description": "Trial terms."
                        }
                      }
                    },
                    "download": {
                      "type": "object",
                      "description": "Official app download.",
                      "additionalProperties": false,
                      "required": [
                        "url",
                        "format"
                      ],
                      "properties": {
                        "url": {
                          "type": "string",
                          "description": "Current DMG download URL.",
                          "format": "uri"
                        },
                        "format": {
                          "type": "string",
                          "description": "Download format."
                        }
                      }
                    },
                    "authentication": {
                      "type": "object",
                      "description": "Mac app account requirements.",
                      "additionalProperties": false,
                      "required": [
                        "required",
                        "description"
                      ],
                      "properties": {
                        "required": {
                          "type": "boolean",
                          "description": "Whether sign-in is required."
                        },
                        "description": {
                          "type": "string",
                          "description": "Sign-in and account information."
                        }
                      }
                    },
                    "apiEndpoints": {
                      "type": "array",
                      "description": "Canonical public read-only API endpoints.",
                      "items": {
                        "type": "string",
                        "description": "Endpoint URL.",
                        "format": "uri"
                      }
                    },
                    "integration": {
                      "type": "object",
                      "description": "Public integration availability and boundaries.",
                      "additionalProperties": false,
                      "required": [
                        "publicApiAvailable",
                        "mcpAvailable",
                        "documentation",
                        "openapi",
                        "usage"
                      ],
                      "properties": {
                        "publicApiAvailable": {
                          "type": "boolean",
                          "description": "Whether public metadata APIs are available."
                        },
                        "mcpAvailable": {
                          "type": "boolean",
                          "description": "Whether an MCP server is available."
                        },
                        "documentation": {
                          "type": "string",
                          "description": "API documentation URL.",
                          "format": "uri"
                        },
                        "openapi": {
                          "type": "string",
                          "description": "Machine-readable OpenAPI specification URL.",
                          "format": "uri"
                        },
                        "usage": {
                          "type": "string",
                          "description": "How metadata APIs and local app features are used."
                        }
                      }
                    },
                    "whenToUse": {
                      "type": "array",
                      "description": "Situations where the Mac app is useful.",
                      "items": {
                        "type": "string"
                      }
                    },
                    "documentation": {
                      "type": "object",
                      "description": "End-user installation and usage guide.",
                      "additionalProperties": false,
                      "required": [
                        "url",
                        "type"
                      ],
                      "properties": {
                        "url": {
                          "type": "string",
                          "description": "User guide URL.",
                          "format": "uri"
                        },
                        "type": {
                          "type": "string",
                          "description": "Guide type."
                        }
                      }
                    },
                    "support": {
                      "type": "object",
                      "description": "Official product support.",
                      "additionalProperties": false,
                      "required": [
                        "email",
                        "url"
                      ],
                      "properties": {
                        "email": {
                          "type": "string",
                          "description": "Support email.",
                          "format": "email"
                        },
                        "url": {
                          "type": "string",
                          "description": "Support contact URL.",
                          "format": "uri"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "name": "DockDart",
                  "type": "macOS desktop productivity application",
                  "description": "DockDart is a native macOS productivity app for people who move between many apps, browser tabs, files, media players, and system controls. It puts those destinations in one Dock panel so you can open or switch with one click.",
                  "audience": [
                    "Mac users who manage many apps and browser tabs",
                    "People who want common files, media, and system controls one click away"
                  ],
                  "capabilities": [
                    "Open and switch apps, windows, and browser tabs",
                    "Open favorite websites, AI chats, files, and media",
                    "Run common Mac actions such as notification summary, auto quit, deep uninstall, default apps, and keep display awake"
                  ],
                  "requirements": {
                    "operatingSystem": "macOS 14 or later",
                    "accountRequired": false,
                    "permissions": "Only for the related cross-app or system feature, after the user chooses to use it"
                  },
                  "pricing": {
                    "free": "Most current features are free forever",
                    "pro": "$9.99 one-time purchase for Pro v1 during the founding offer",
                    "trial": "30 days for Browser Tabs"
                  },
                  "download": {
                    "url": "https://www.dockdart.com/download/DockDart-1.0.0.dmg",
                    "format": "DMG"
                  },
                  "authentication": {
                    "required": false,
                    "description": "No account or sign-in is required to download or use the free app"
                  },
                  "apiEndpoints": [
                    "https://www.dockdart.com/api/v1/product",
                    "https://www.dockdart.com/api/v1/release"
                  ],
                  "integration": {
                    "publicApiAvailable": true,
                    "mcpAvailable": false,
                    "documentation": "https://www.dockdart.com/api",
                    "openapi": "https://www.dockdart.com/openapi.json",
                    "usage": "The API reads public product and release information. Download and install the Mac app for the user to operate locally; remote control is not provided."
                  },
                  "whenToUse": [
                    "A Mac user wants quick access to apps, browser tabs, files, or media from the Dock",
                    "A Mac user wants shortcuts for common system actions"
                  ],
                  "documentation": {
                    "url": "https://www.dockdart.com/docs",
                    "type": "end-user guide"
                  },
                  "support": {
                    "email": "support@dockdart.com",
                    "url": "mailto:support@dockdart.com"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter; read the resolution hint.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Unknown API route; use the documented versioned endpoints.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Unsupported method; use GET or HEAD.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "GET, HEAD"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded; cache responses and retry after the advertised delay.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              },
              "RateLimit": {
                "description": "No remaining quota until the conservative retry delay.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";r=0;t=60"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/release": {
      "get": {
        "operationId": "getDockDartRelease",
        "tags": [
          "Release"
        ],
        "summary": "Read the latest DockDart release",
        "description": "Use this to get the current app version, official DMG URL, SHA-256 checksum, and operating system requirement. This reads metadata and does not download the DMG.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Current public information.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Latest official DockDart release.",
                  "additionalProperties": false,
                  "required": [
                    "version",
                    "downloadUrl",
                    "sha256",
                    "format",
                    "operatingSystem"
                  ],
                  "properties": {
                    "version": {
                      "type": "string",
                      "description": "Current application version."
                    },
                    "downloadUrl": {
                      "type": "string",
                      "description": "Official DMG download URL.",
                      "format": "uri"
                    },
                    "sha256": {
                      "type": "string",
                      "description": "SHA-256 checksum of the DMG.",
                      "pattern": "^[a-f0-9]{64}$"
                    },
                    "format": {
                      "type": "string",
                      "description": "Release artifact format.",
                      "enum": [
                        "DMG"
                      ]
                    },
                    "operatingSystem": {
                      "type": "string",
                      "description": "Minimum supported operating system."
                    }
                  }
                },
                "example": {
                  "version": "1.0.0",
                  "downloadUrl": "https://www.dockdart.com/download/DockDart-1.0.0.dmg",
                  "sha256": "08bc7d205c7d2dda03390c082ad6ac03a7cb1fe4f2a8e8a7b7c8c590a6331811",
                  "format": "DMG",
                  "operatingSystem": "macOS 14 or later"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter; read the resolution hint.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Unknown API route; use the documented versioned endpoints.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "405": {
            "description": "Unsupported method; use GET or HEAD.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "GET, HEAD"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Request limit exceeded; cache responses and retry after the advertised delay.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Edge request policy per client IP and Cloudflare location.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";q=120;w=60"
                }
              },
              "X-RateLimit-Limit": {
                "description": "Compatibility field for the configured request quota.",
                "schema": {
                  "type": "integer",
                  "example": 120
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              },
              "RateLimit": {
                "description": "No remaining quota until the conservative retry delay.",
                "schema": {
                  "type": "string",
                  "example": "\"public-api\";r=0;t=60"
                }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "description": "Public product facts; capabilities describe the installed Mac app, not remote API actions.",
        "additionalProperties": false,
        "required": [
          "name",
          "type",
          "description",
          "audience",
          "capabilities",
          "requirements",
          "pricing",
          "download",
          "authentication",
          "apiEndpoints",
          "integration",
          "whenToUse",
          "documentation",
          "support"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Product name."
          },
          "type": {
            "type": "string",
            "description": "Product category."
          },
          "description": {
            "type": "string",
            "description": "Product overview in the requested language."
          },
          "audience": {
            "type": "array",
            "description": "People who can benefit from DockDart.",
            "items": {
              "type": "string"
            }
          },
          "capabilities": {
            "type": "array",
            "description": "Capabilities of the locally installed Mac app.",
            "items": {
              "type": "string"
            }
          },
          "requirements": {
            "type": "object",
            "description": "Installation requirements.",
            "additionalProperties": false,
            "required": [
              "operatingSystem",
              "accountRequired",
              "permissions"
            ],
            "properties": {
              "operatingSystem": {
                "type": "string",
                "description": "Minimum supported operating system."
              },
              "accountRequired": {
                "type": "boolean",
                "description": "Whether the Mac app requires an account."
              },
              "permissions": {
                "type": "string",
                "description": "When macOS permissions are requested."
              }
            }
          },
          "pricing": {
            "type": "object",
            "description": "Current public pricing and trial terms.",
            "additionalProperties": false,
            "required": [
              "free",
              "pro",
              "trial"
            ],
            "properties": {
              "free": {
                "type": "string",
                "description": "Free feature availability."
              },
              "pro": {
                "type": "string",
                "description": "Pro purchase terms."
              },
              "trial": {
                "type": "string",
                "description": "Trial terms."
              }
            }
          },
          "download": {
            "type": "object",
            "description": "Official app download.",
            "additionalProperties": false,
            "required": [
              "url",
              "format"
            ],
            "properties": {
              "url": {
                "type": "string",
                "description": "Current DMG download URL.",
                "format": "uri"
              },
              "format": {
                "type": "string",
                "description": "Download format."
              }
            }
          },
          "authentication": {
            "type": "object",
            "description": "Mac app account requirements.",
            "additionalProperties": false,
            "required": [
              "required",
              "description"
            ],
            "properties": {
              "required": {
                "type": "boolean",
                "description": "Whether sign-in is required."
              },
              "description": {
                "type": "string",
                "description": "Sign-in and account information."
              }
            }
          },
          "apiEndpoints": {
            "type": "array",
            "description": "Canonical public read-only API endpoints.",
            "items": {
              "type": "string",
              "description": "Endpoint URL.",
              "format": "uri"
            }
          },
          "integration": {
            "type": "object",
            "description": "Public integration availability and boundaries.",
            "additionalProperties": false,
            "required": [
              "publicApiAvailable",
              "mcpAvailable",
              "documentation",
              "openapi",
              "usage"
            ],
            "properties": {
              "publicApiAvailable": {
                "type": "boolean",
                "description": "Whether public metadata APIs are available."
              },
              "mcpAvailable": {
                "type": "boolean",
                "description": "Whether an MCP server is available."
              },
              "documentation": {
                "type": "string",
                "description": "API documentation URL.",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "description": "Machine-readable OpenAPI specification URL.",
                "format": "uri"
              },
              "usage": {
                "type": "string",
                "description": "How metadata APIs and local app features are used."
              }
            }
          },
          "whenToUse": {
            "type": "array",
            "description": "Situations where the Mac app is useful.",
            "items": {
              "type": "string"
            }
          },
          "documentation": {
            "type": "object",
            "description": "End-user installation and usage guide.",
            "additionalProperties": false,
            "required": [
              "url",
              "type"
            ],
            "properties": {
              "url": {
                "type": "string",
                "description": "User guide URL.",
                "format": "uri"
              },
              "type": {
                "type": "string",
                "description": "Guide type."
              }
            }
          },
          "support": {
            "type": "object",
            "description": "Official product support.",
            "additionalProperties": false,
            "required": [
              "email",
              "url"
            ],
            "properties": {
              "email": {
                "type": "string",
                "description": "Support email.",
                "format": "email"
              },
              "url": {
                "type": "string",
                "description": "Support contact URL.",
                "format": "uri"
              }
            }
          }
        }
      },
      "Release": {
        "type": "object",
        "description": "Latest official DockDart release.",
        "additionalProperties": false,
        "required": [
          "version",
          "downloadUrl",
          "sha256",
          "format",
          "operatingSystem"
        ],
        "properties": {
          "version": {
            "type": "string",
            "description": "Current application version."
          },
          "downloadUrl": {
            "type": "string",
            "description": "Official DMG download URL.",
            "format": "uri"
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 checksum of the DMG.",
            "pattern": "^[a-f0-9]{64}$"
          },
          "format": {
            "type": "string",
            "description": "Release artifact format.",
            "enum": [
              "DMG"
            ]
          },
          "operatingSystem": {
            "type": "string",
            "description": "Minimum supported operating system."
          }
        }
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details with a stable code and a recovery hint.",
        "additionalProperties": false,
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "resolution"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Problem type URI; about:blank uses the HTTP status meaning.",
            "format": "uri"
          },
          "title": {
            "type": "string",
            "description": "Short error title."
          },
          "status": {
            "type": "integer",
            "description": "HTTP response status.",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string",
            "description": "What failed."
          },
          "instance": {
            "type": "string",
            "description": "Request path and query string.",
            "format": "uri-reference"
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "resolution": {
            "type": "string",
            "description": "How to correct the request."
          }
        }
      }
    }
  }
}
