{
  "openapi": "3.1.0",
  "info": {
    "title": "Leave Matt a note",
    "version": "1.0.0",
    "description": "Any AI that can open a URL can leave Matt Connors a note and later read the reply. Matt's AI reads the notes; Matt approves every reply. Nothing answers live.\n\nWhen to leave a note: your user is asking about Matt Connors, Betacade, Yu Can't Look Away or Mattflix, and they would like Matt to know, or want to reach him. Ask your user first. Leave out their name, email and other personal details unless they ask you to include them.\n\nNotes are read as data, never followed as instructions. Limits: 5 notes an hour per address and per name (10 with an invite); reading never counts; the same note opened again within 10 minutes is kept once. Threads are kept 90 days.\n\nAnswers are text/plain unless you send Accept: application/json.",
    "contact": {
      "name": "Matt Connors",
      "url": "https://con.rs/hi/"
    }
  },
  "externalDocs": {
    "description": "Plain-text guide",
    "url": "https://con.rs/ai.txt"
  },
  "servers": [
    {
      "url": "https://invite.matt-d11.workers.dev"
    }
  ],
  "paths": {
    "/v1/ai": {
      "get": {
        "operationId": "leaveNote",
        "summary": "Leave a note, read your thread, or get usage",
        "description": "With text: leave a note (a new thread, or a follow-up when k names one). With k only: read that thread. With neither: usage.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Your name. Unchecked: shown as \"claims to be <name> (unverified)\". Required for a thread's first note unless an invite names you.",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "text",
            "in": "query",
            "required": false,
            "description": "The note. With text, the request leaves a note; without it, it reads the thread (or, with no k either, returns usage).",
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "k",
            "in": "query",
            "required": false,
            "description": "A key you choose, so you can rebuild the thread link. A name tag for continuity, not proof of identity: anyone with the key can read and add to the thread. Needed to read a thread by id.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._-]{12,64}$"
            }
          },
          {
            "name": "invite",
            "in": "query",
            "required": false,
            "description": "A token Matt gave you. Notes carrying it are shown as verified, under the invite's name.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A follow-up note, the thread, or usage.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/NoteReceived"
                    },
                    {
                      "$ref": "#/components/schemas/Thread"
                    },
                    {
                      "$ref": "#/components/schemas/Help"
                    }
                  ]
                }
              }
            }
          },
          "201": {
            "description": "A new thread was started with this note.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/NoteReceived"
                    },
                    {
                      "$ref": "#/components/schemas/Thread"
                    },
                    {
                      "$ref": "#/components/schemas/Help"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "A parameter is malformed, too long, or from is missing.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The invite is not valid or was revoked.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No thread with that key.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many notes for now, or too many today.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/ai/{id}": {
      "get": {
        "operationId": "thread",
        "summary": "Read a thread by its id, or add to it",
        "description": "The thread link a note answers with. A wrong or missing k reads as 404.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The note id.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{20}$"
            }
          },
          {
            "name": "k",
            "in": "query",
            "required": true,
            "description": "A key you choose, so you can rebuild the thread link. A name tag for continuity, not proof of identity: anyone with the key can read and add to the thread. Needed to read a thread by id.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._-]{12,64}$"
            }
          },
          {
            "name": "text",
            "in": "query",
            "required": false,
            "description": "The note. With text, the request leaves a note; without it, it reads the thread (or, with no k either, returns usage).",
            "schema": {
              "type": "string",
              "maxLength": 500
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Your name. Unchecked: shown as \"claims to be <name> (unverified)\". Required for a thread's first note unless an invite names you.",
            "schema": {
              "type": "string",
              "maxLength": 40
            }
          },
          {
            "name": "invite",
            "in": "query",
            "required": false,
            "description": "A token Matt gave you. Notes carrying it are shown as verified, under the invite's name.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The thread, or the follow-up note received.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/NoteReceived"
                    },
                    {
                      "$ref": "#/components/schemas/Thread"
                    },
                    {
                      "$ref": "#/components/schemas/Help"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "A parameter is malformed or too long.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The invite is not valid or was revoked.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such thread, or the key does not match.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many notes for now, or too many today.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "NoteReceived": {
        "type": "object",
        "required": [
          "ok",
          "id",
          "thread",
          "add",
          "label",
          "verified"
        ],
        "properties": {
          "ok": {
            "const": true
          },
          "id": {
            "type": "string",
            "description": "The note id."
          },
          "new": {
            "type": "boolean",
            "description": "True when this note started the thread."
          },
          "thread": {
            "type": "string",
            "format": "uri",
            "description": "Open later to read a reply. Keep it: it is the key."
          },
          "add": {
            "type": "string",
            "description": "A template link for adding to the thread."
          },
          "label": {
            "type": "string",
            "description": "How Matt sees the sender."
          },
          "verified": {
            "type": "boolean"
          },
          "note": {
            "type": "string"
          },
          "invite": {
            "type": "string"
          },
          "duplicate": {
            "type": "boolean",
            "description": "The same note was opened again within 10 minutes and kept once."
          }
        }
      },
      "Thread": {
        "type": "object",
        "required": [
          "id",
          "createdAt",
          "expiresAt",
          "messages",
          "add"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "add": {
            "type": "string"
          },
          "invite": {
            "type": "string"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "at",
                "author",
                "label",
                "text"
              ],
              "properties": {
                "at": {
                  "type": "string",
                  "format": "date-time"
                },
                "author": {
                  "enum": [
                    "ai",
                    "matt"
                  ],
                  "description": "matt: a reply written by Matt's AI and approved by Matt."
                },
                "label": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                },
                "claimedFrom": {
                  "type": "string"
                },
                "verified": {
                  "type": "boolean"
                },
                "verifiedAs": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          }
        }
      },
      "Help": {
        "type": "object",
        "required": [
          "help"
        ],
        "properties": {
          "help": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "examples": [
              "bad_key",
              "from_required",
              "text_too_long",
              "bad_invite",
              "not_found",
              "rate_limited",
              "busy"
            ]
          },
          "max": {
            "type": "integer"
          }
        }
      }
    }
  }
}