{
  "openapi": "3.1.0",
  "info": {
    "title": "OneMacApp API",
    "version": "1.0.0",
    "summary": "Read-only catalog of OneMacApp's Mac tools, pricing and requirements.",
    "description": "Public, free and keyless. OneMacApp is a native macOS app; this API describes it so agents can find the right tool, check requirements and give users a checkout link. It does not process files. Versioning: breaking changes get a new path (/api/v2); /api/v1 stays as is. Rate limit: 120 requests per minute per IP. Errors use RFC 9457 problem+json with a stable `code`.",
    "contact": {
      "name": "OneMacApp support",
      "email": "hello@onemacapp.com",
      "url": "https://onemacapp.com/contact"
    },
    "termsOfService": "https://onemacapp.com/terms"
  },
  "externalDocs": {
    "description": "Developer docs",
    "url": "https://onemacapp.com/developers"
  },
  "servers": [
    {
      "url": "https://onemacapp.com/api/v1"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Catalog"
    },
    {
      "name": "Commerce"
    }
  ],
  "paths": {
    "/app": {
      "get": {
        "operationId": "getAppInfo",
        "tags": [
          "Catalog"
        ],
        "summary": "App info and system requirements",
        "responses": {
          "200": {
            "description": "The app.",
            "headers": {
              "RateLimit": {
                "description": "IETF RateLimit header: limit, remaining and reset (seconds).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "description": "Quota policy, e.g. `120;w=60`.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Version of this API that answered.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/App"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Wait for the `Retry-After` seconds.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/tools": {
      "get": {
        "operationId": "searchTools",
        "tags": [
          "Catalog"
        ],
        "summary": "List or search tools",
        "description": "Every tool, or those matching `q` (all words must match) and/or `category`. Paginate with `cursor`.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Keywords, e.g. `compress video`."
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "video",
                "audio",
                "images",
                "pdf",
                "ai",
                "files",
                "utilities"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "`next_cursor` from the previous page."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of tools.",
            "headers": {
              "RateLimit": {
                "description": "IETF RateLimit header: limit, remaining and reset (seconds).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "description": "Quota policy, e.g. `120;w=60`.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Version of this API that answered.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolList"
                }
              }
            }
          },
          "400": {
            "description": "Bad parameter.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Wait for the `Retry-After` seconds.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/tools/{slug}": {
      "get": {
        "operationId": "getTool",
        "tags": [
          "Catalog"
        ],
        "summary": "One tool in full",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "compress-video"
          }
        ],
        "responses": {
          "200": {
            "description": "The tool.",
            "headers": {
              "RateLimit": {
                "description": "IETF RateLimit header: limit, remaining and reset (seconds).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "description": "Quota policy, e.g. `120;w=60`.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Version of this API that answered.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolDetail"
                }
              }
            }
          },
          "404": {
            "description": "No tool with that slug.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Wait for the `Retry-After` seconds.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/categories": {
      "get": {
        "operationId": "listCategories",
        "tags": [
          "Catalog"
        ],
        "summary": "Tool categories",
        "responses": {
          "200": {
            "description": "Categories.",
            "headers": {
              "RateLimit": {
                "description": "IETF RateLimit header: limit, remaining and reset (seconds).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "description": "Quota policy, e.g. `120;w=60`.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Version of this API that answered.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Category"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Wait for the `Retry-After` seconds.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "operationId": "getPricing",
        "tags": [
          "Commerce"
        ],
        "summary": "Plans, prices and checkout links",
        "responses": {
          "200": {
            "description": "Pricing.",
            "headers": {
              "RateLimit": {
                "description": "IETF RateLimit header: limit, remaining and reset (seconds).",
                "schema": {
                  "type": "string"
                }
              },
              "RateLimit-Policy": {
                "description": "Quota policy, e.g. `120;w=60`.",
                "schema": {
                  "type": "string"
                }
              },
              "API-Version": {
                "description": "Version of this API that answered.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pricing"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited. Wait for the `Retry-After` seconds.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Server error.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable code.",
            "enum": [
              "not_found",
              "tool_not_found",
              "invalid_category",
              "invalid_limit",
              "rate_limited",
              "internal_error"
            ]
          },
          "hint": {
            "type": "string",
            "description": "What to do next."
          },
          "docs": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "code"
        ]
      },
      "ToolSummary": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "video",
              "audio",
              "images",
              "pdf",
              "ai",
              "files",
              "utilities"
            ]
          },
          "summary": {
            "type": "string"
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "markdown_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          }
        },
        "required": [
          "slug",
          "name",
          "category",
          "summary",
          "url",
          "markdown_url"
        ]
      },
      "ToolList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ToolSummary"
            }
          },
          "total": {
            "type": "integer"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          },
          "has_more": {
            "type": "boolean"
          }
        },
        "required": [
          "data",
          "total",
          "next_cursor",
          "has_more"
        ]
      },
      "ToolDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ToolSummary"
          },
          {
            "type": "object",
            "properties": {
              "description": {
                "type": "string"
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    }
                  }
                }
              },
              "features": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "body": {
                      "type": "string"
                    }
                  }
                }
              },
              "specs": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "value": {
                      "type": "string"
                    }
                  }
                }
              },
              "faqs": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "question": {
                      "type": "string"
                    },
                    "answer": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "required": [
              "description",
              "steps",
              "features",
              "specs",
              "faqs"
            ]
          }
        ]
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "tool_count": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "tool_count"
        ]
      },
      "Pricing": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string"
          },
          "billing": {
            "type": "string",
            "enum": [
              "one_time"
            ]
          },
          "subscription": {
            "type": "boolean"
          },
          "updates_included": {
            "type": "boolean"
          },
          "refund_days": {
            "type": "integer"
          },
          "discount": {
            "type": [
              "object",
              "null"
            ],
            "description": "The launch discount while it lasts: it ends after `limit` licences are sold.",
            "properties": {
              "name": {
                "type": "string"
              },
              "percent": {
                "type": "number"
              },
              "applied_automatically": {
                "type": "boolean"
              },
              "limit": {
                "type": "integer"
              },
              "remaining": {
                "type": "integer"
              }
            }
          },
          "plans": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "seats": {
                  "type": "integer"
                },
                "description": {
                  "type": "string"
                },
                "list_price": {
                  "type": "number"
                },
                "price": {
                  "type": "number",
                  "description": "What the buyer pays, discount applied."
                },
                "checkout_url": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "required": [
                "seats",
                "list_price",
                "price",
                "checkout_url"
              ]
            }
          }
        },
        "required": [
          "currency",
          "billing",
          "plans"
        ]
      },
      "App": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "tagline": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "minimum_os": {
            "type": "string"
          },
          "latest_version": {
            "type": [
              "string",
              "null"
            ]
          },
          "tool_count": {
            "type": "integer"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "privacy": {
            "type": "string"
          },
          "website": {
            "type": "string",
            "format": "uri"
          },
          "support_email": {
            "type": "string",
            "format": "email"
          },
          "publisher": {
            "type": "string"
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "llms_txt": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "name",
          "platform",
          "minimum_os",
          "tool_count"
        ]
      }
    }
  }
}