{
  "openapi": "3.1.0",
  "info": {
    "title": "Farmers Platform API",
    "version": "1.1.0",
    "description": "Farmers public-data API. Scoped bearer keys issued by administrators. Health and identity checks, read-only published content, optional signed outgoing webhooks. No private data, OAuth grants or payment processing."
  },
  "servers": [
    {
      "url": "https://marketplace.bluepeople.co.za/wp-json/farmers-platform/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAppToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Farmers developer key"
      }
    },
    "schemas": {
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          },
          "has_more": {
            "type": "boolean"
          },
          "source": {
            "type": "string"
          }
        }
      },
      "Post": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "type": {
            "type": "string",
            "enum": [
              "post",
              "seed"
            ]
          },
          "text": {
            "type": "string"
          },
          "place": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "author": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "username": {
                "type": "string"
              }
            }
          }
        }
      },
      "Farm": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "office",
              "shop"
            ]
          },
          "tagline": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          }
        }
      },
      "OutgoingEvent": {
        "type": "object",
        "required": [
          "id",
          "event",
          "api_version",
          "data",
          "sent_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "event": {
            "type": "string",
            "enum": [
              "post.published",
              "connection.test"
            ]
          },
          "api_version": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "sent_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "summary": "Public API status",
        "security": [],
        "responses": {
          "200": {
            "description": "Operational API metadata"
          }
        }
      }
    },
    "/posts": {
      "get": {
        "summary": "List published Posts and Seed-tagged Posts",
        "security": [
          {
            "BearerAppToken": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated public Posts"
          },
          "401": {
            "description": "Missing/revoked developer token"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/farms": {
      "get": {
        "summary": "List public business Farms",
        "security": [
          {
            "BearerAppToken": []
          }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated published Farms"
          },
          "401": {
            "description": "Missing/revoked developer token"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/whoami": {
      "get": {
        "summary": "Verify an API application token and inspect permitted scopes",
        "security": [
          {
            "BearerAppToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Authenticated application identity and public.read scope"
          },
          "401": {
            "description": "Missing, invalid, or revoked token"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/readiness": {
      "get": {
        "summary": "Administrator-only server readiness: WordPress session and REST nonce required",
        "security": [],
        "responses": {
          "200": {
            "description": "Admin-only infrastructure readiness"
          },
          "403": {
            "description": "Not an administrator"
          }
        }
      }
    }
  },
  "webhooks": {
    "postPublished": {
      "post": {
        "summary": "Signed public Post event sent to an administrator-approved partner HTTPS endpoint",
        "parameters": [
          {
            "name": "X-Farmers-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Farmers-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Farmers-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutgoingEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Receiver accepted the event; not proof of downstream processing"
          }
        }
      }
    },
    "connectionTest": {
      "post": {
        "summary": "Administrator-initiated signed connectivity test without business side effects",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutgoingEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Receiver accepted the test payload"
          }
        }
      }
    }
  }
}
