{
  "openapi": "3.1.0",
  "info": {
    "title": "Chekku API",
    "version": "1.0.0",
    "summary": "Shareable checklists with no accounts.",
    "description": "The link is the list: anyone holding a list URL can read and edit it. Create a list, then give the user its url. Items can be named by id or by text. Docs: https://www.chekku.app/mcp"
  },
  "servers": [
    {
      "url": "https://www.chekku.app"
    }
  ],
  "paths": {
    "/api/v1/lists": {
      "post": {
        "operationId": "createList",
        "summary": "Create a checklist",
        "description": "Returns the list including its shareable url. Always give the user that url.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 200
                    }
                  },
                  "emoji": {
                    "type": "string",
                    "maxLength": 8
                  },
                  "numbering": {
                    "type": "string",
                    "enum": [
                      "none",
                      "numeric",
                      "step"
                    ]
                  },
                  "accent": {
                    "type": "string",
                    "enum": [
                      "moss",
                      "clay",
                      "indigo",
                      "plum",
                      "sun"
                    ]
                  }
                },
                "required": [
                  "title"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/List"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/lists/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The list id (the last part of its URL).",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "getList",
        "summary": "Read a checklist",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "markdown"
              ]
            },
            "description": "markdown returns text/markdown instead of JSON."
          }
        ],
        "responses": {
          "200": {
            "description": "The list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/List"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateList",
        "summary": "Rename or restyle a checklist",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "emoji": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 8
                  },
                  "numbering": {
                    "type": "string",
                    "enum": [
                      "none",
                      "numeric",
                      "step"
                    ]
                  },
                  "sort": {
                    "type": "string",
                    "enum": [
                      "manual",
                      "alpha",
                      "unchecked",
                      "priority"
                    ]
                  },
                  "accent": {
                    "type": "string",
                    "enum": [
                      "moss",
                      "clay",
                      "indigo",
                      "plum",
                      "sun"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/List"
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteList",
        "summary": "Delete a checklist for everyone",
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/lists/{id}/items": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The list id (the last part of its URL).",
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "operationId": "addItems",
        "summary": "Add items",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 200
                    },
                    "minItems": 1
                  },
                  "position": {
                    "type": "string",
                    "enum": [
                      "end",
                      "start"
                    ]
                  }
                },
                "required": [
                  "items"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Items added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "list": {
                      "$ref": "#/components/schemas/List"
                    },
                    "added": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Item"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "checkItems",
        "summary": "Check or uncheck several items, or reset all",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Item ids or texts."
                  },
                  "checked": {
                    "type": "boolean",
                    "default": true
                  },
                  "reset": {
                    "type": "boolean",
                    "description": "true unchecks every item and ignores the other fields."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "list": {
                      "$ref": "#/components/schemas/List"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Item"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/lists/{id}/items/{item}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "The list id (the last part of its URL).",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "item",
          "in": "path",
          "required": true,
          "description": "The item id, or its text (case-insensitive; a unique partial match works).",
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "operationId": "updateItem",
        "summary": "Edit one item",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "comment": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "priority": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "enum": [
                      "high",
                      "medium",
                      "low",
                      "none",
                      null
                    ]
                  },
                  "checked": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "list": {
                      "$ref": "#/components/schemas/List"
                    },
                    "item": {
                      "$ref": "#/components/schemas/Item"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "removeItem",
        "summary": "Remove one item",
        "responses": {
          "200": {
            "description": "Removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "list": {
                      "$ref": "#/components/schemas/List"
                    },
                    "removed": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "text": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Item": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "position": {
            "type": "integer",
            "description": "1-based display position."
          },
          "label": {
            "type": "string",
            "description": "\"3.\" or \"Step 3\" when the list is numbered."
          },
          "text": {
            "type": "string"
          },
          "checked": {
            "type": "boolean"
          },
          "comment": {
            "type": "string"
          },
          "priority": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "high",
              "medium",
              "low",
              null
            ]
          }
        },
        "required": [
          "id",
          "position",
          "text",
          "checked",
          "comment",
          "priority"
        ]
      },
      "List": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Share this with the user."
          },
          "title": {
            "type": "string"
          },
          "emoji": {
            "type": [
              "string",
              "null"
            ]
          },
          "numbering": {
            "type": "string",
            "enum": [
              "none",
              "numeric",
              "step"
            ]
          },
          "sort": {
            "type": "string",
            "enum": [
              "manual",
              "alpha",
              "unchecked",
              "priority"
            ]
          },
          "accent": {
            "type": "string",
            "enum": [
              "moss",
              "clay",
              "indigo",
              "plum",
              "sun"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "live",
              "snapshot"
            ]
          },
          "editable": {
            "type": "boolean"
          },
          "progress": {
            "type": "object",
            "properties": {
              "done": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            }
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          },
          "createdAt": {
            "type": "integer",
            "description": "Unix milliseconds."
          },
          "updatedAt": {
            "type": "integer",
            "description": "Unix milliseconds."
          }
        },
        "required": [
          "id",
          "url",
          "title",
          "items",
          "progress",
          "editable",
          "kind"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}