{
  "openapi": "3.1.0",
  "info": {
    "title": "Pine public agent API",
    "version": "1.0.0",
    "summary": "Read-only facts about Pine releases, installation and documentation.",
    "description": "Pine is an MIT-licensed Pi extension for terminal widgets, notes, tasks and saved custom agents in herdr. Pine runs locally; this API only publishes facts about Pine 0.13.0. No authentication. It never installs anything and never receives project content. Errors use RFC 9457 problem details. The same operations are available as MCP tools at https://pine-pi.vercel.app/mcp.",
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    },
    "contact": {
      "name": "Pine on GitHub",
      "url": "https://github.com/johnlindquist/pine/issues"
    }
  },
  "servers": [
    {
      "url": "https://pine-pi.vercel.app"
    }
  ],
  "externalDocs": {
    "url": "https://pine-pi.vercel.app/docs/api.html",
    "description": "Pine API and MCP guide"
  },
  "tags": [
    {
      "name": "Pine",
      "description": "Pine release, install and documentation facts"
    }
  ],
  "paths": {
    "/api/v1/release": {
      "get": {
        "operationId": "getRelease",
        "summary": "Get the latest Pine release",
        "description": "Latest version, release page, the pi install command and the SHA-256 checksum of each renderer binary.",
        "parameters": [],
        "tags": [
          "Pine"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Release"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Problem"
          },
          "404": {
            "$ref": "#/components/responses/Problem"
          },
          "405": {
            "$ref": "#/components/responses/Problem"
          },
          "500": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/api/v1/install": {
      "get": {
        "operationId": "getInstallSteps",
        "summary": "Get installation steps",
        "description": "Ordered steps from the Pine agent installation guide with exact commands. Pass step for a single step.",
        "parameters": [
          {
            "name": "step",
            "in": "query",
            "required": false,
            "description": "Step number from the guide.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "tags": [
          "Pine"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Install"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Problem"
          },
          "404": {
            "$ref": "#/components/responses/Problem"
          },
          "405": {
            "$ref": "#/components/responses/Problem"
          },
          "500": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    },
    "/api/v1/docs/search": {
      "get": {
        "operationId": "searchDocs",
        "summary": "Search the Pine documentation",
        "description": "Find documentation sections about a topic. Returns links and short excerpts.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Words to search for, up to 200 characters.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum results.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 5
            }
          }
        ],
        "tags": [
          "Pine"
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResults"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Problem"
          },
          "404": {
            "$ref": "#/components/responses/Problem"
          },
          "405": {
            "$ref": "#/components/responses/Problem"
          },
          "500": {
            "$ref": "#/components/responses/Problem"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Problem": {
        "description": "RFC 9457 problem details",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "code",
          "detail",
          "hint"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "detail": {
            "type": "string"
          },
          "hint": {
            "type": "string",
            "description": "How to resolve the error."
          },
          "docs": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Binary": {
        "type": "object",
        "required": [
          "name",
          "platform",
          "bytes",
          "sha256",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "platform": {
            "type": "string"
          },
          "bytes": {
            "type": "integer"
          },
          "sha256": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Release": {
        "type": "object",
        "required": [
          "version",
          "tag",
          "releaseUrl",
          "install",
          "binaries"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "tag": {
            "type": "string"
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time"
          },
          "releaseUrl": {
            "type": "string",
            "format": "uri"
          },
          "install": {
            "type": "object",
            "properties": {
              "command": {
                "type": "string"
              },
              "where": {
                "type": "string"
              },
              "requires": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "verify": {
                "type": "string"
              }
            }
          },
          "source": {
            "type": "string",
            "format": "uri"
          },
          "license": {
            "type": "string"
          },
          "binaries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Binary"
            }
          },
          "checksumsUrl": {
            "type": "string",
            "format": "uri"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "Step": {
        "type": "object",
        "required": [
          "number",
          "title",
          "commands"
        ],
        "properties": {
          "number": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "commands": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "where": {
                  "type": "string",
                  "enum": [
                    "terminal",
                    "inside Pi"
                  ]
                },
                "code": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Install": {
        "type": "object",
        "required": [
          "version",
          "guide"
        ],
        "properties": {
          "version": {
            "type": "string"
          },
          "guide": {
            "type": "string",
            "format": "uri"
          },
          "markdown": {
            "type": "string",
            "format": "uri"
          },
          "steps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Step"
            }
          },
          "step": {
            "$ref": "#/components/schemas/Step"
          }
        }
      },
      "SearchResults": {
        "type": "object",
        "required": [
          "query",
          "total",
          "results"
        ],
        "properties": {
          "query": {
            "type": "string"
          },
          "total": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "markdown": {
                  "type": "string",
                  "format": "uri"
                },
                "score": {
                  "type": "number"
                },
                "snippet": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}