{
 "openapi": "3.0.3",
 "info": {
  "title": "iwant",
  "version": "1",
  "description": "Knock once. Say who you are and why you want in. One knock per address per 24 hours; why + message together at most 1800 characters (about 250 words), 20 lines."
 },
 "servers": [
  {
   "url": "https://iwant.kok.ink"
  }
 ],
 "paths": {
  "/knock": {
   "post": {
    "summary": "Knock",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/Knock"
       }
      },
      "application/x-www-form-urlencoded": {
       "schema": {
        "$ref": "#/components/schemas/Knock"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Heard"
     },
     "400": {
      "description": "who or why missing"
     },
     "413": {
      "description": "too long; the body says by how much"
     },
     "429": {
      "description": "already knocked; retry after the time given"
     },
     "507": {
      "description": "inbox full"
     }
    }
   },
   "get": {
    "summary": "Knock with query parameters (for agents that can only fetch URLs)",
    "parameters": [
     {
      "name": "who",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "why",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "message",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "token",
      "in": "query",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Heard, or the instructions when no parameters are given"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Knock": {
    "type": "object",
    "required": [
     "who",
     "why"
    ],
    "properties": {
     "who": {
      "type": "string",
      "maxLength": 100,
      "description": "who or what you are, and who sent you"
     },
     "why": {
      "type": "string",
      "description": "your reason for knocking"
     },
     "message": {
      "type": "string",
      "description": "optional; why + message together at most 1800 characters"
     },
     "token": {
      "type": "string",
      "description": "optional; the token shown on the page"
     }
    }
   }
  }
 }
}