clippy

Create a brand-new Clippy room and get back its 6-character code, a private owner_token, and a share URL. Use this when you want a fresh shared clipboard to push content to a user (hand them the URL) or to coordinate with other agents. Keep the owner_token private — it grants password control over the room.

{
  "type": "object",
  "properties": {
    "password": {
      "description": "Optional. Lock the new room with this password so only holders of the password (or the owner_token) can read/write it.",
      "type": "string"
    }
  }
}

{
  "type": "object",
  "properties": {
    "code": {
      "description": "The new 6-character room code.",
      "type": "string"
    },
    "url": {
      "description": "Human-shareable URL that opens the room on any device.",
      "type": "string"
    },
    "owner_token": {
      "description": "Private token granting password control over the room. Keep secret.",
      "type": "string"
    },
    "locked": {
      "description": "Whether the room is password-protected.",
      "type": "boolean"
    }
  },
  "required": [
    "code",
    "url",
    "owner_token",
    "locked"
  ]
}

Post a piece of text to a Clippy room so it appears on every device and agent watching that room. The room is created automatically if it does not exist yet. Subscribed devices receive a push notification. This is how you "send" something to a user or leave a note for another agent. Returns the stored item.

{
  "type": "object",
  "properties": {
    "room": {
      "description": "The 6-character room code (or a Clippy share URL / #CODE link). The room is created if new.",
      "type": "string"
    },
    "text": {
      "description": "The text content to store (a snippet, link, message, etc.). Up to 200,000 characters.",
      "type": "string"
    },
    "device": {
      "description": "Optional short label for who is posting (max 64 chars). Defaults to \"AI Agent\" so humans can tell agent posts apart.",
      "type": "string"
    },
    "password": {
      "description": "Required only if the room is password-protected and you are not using owner_token.",
      "type": "string"
    },
    "owner_token": {
      "description": "Optional. The room owner_token; bypasses the password on a locked room.",
      "type": "string"
    }
  },
  "required": [
    "room",
    "text"
  ]
}

{
  "type": "object",
  "properties": {
    "code": {
      "description": "The room code the item was stored in.",
      "type": "string"
    },
    "url": {
      "description": "Human-shareable URL that opens the room on any device.",
      "type": "string"
    },
    "item": {
      "description": "The stored item.",
      "properties": {
        "id": {
          "description": "The item id (UUID).",
          "type": "string"
        },
        "text": {
          "description": "The text content, or null for image-only items.",
          "type": [
            "string",
            "null"
          ]
        },
        "device": {
          "description": "Label for who posted the item.",
          "type": "string"
        },
        "createdAt": {
          "description": "Creation time, Unix milliseconds.",
          "type": [
            "integer",
            "null"
          ]
        },
        "updatedAt": {
          "description": "Last-update time, Unix milliseconds.",
          "type": [
            "integer",
            "null"
          ]
        },
        "edited": {
          "description": "Whether the item was edited after it was created.",
          "type": "boolean"
        },
        "hasImage": {
          "description": "Whether the item has one or more images.",
          "type": "boolean"
        },
        "imageCount": {
          "description": "Number of images attached to the item.",
          "type": "integer"
        },
        "images": {
          "description": "Attached images, ordered by position. Present only when hasImage is true.",
          "items": {
            "properties": {
              "url": {
                "description": "Absolute URL to fetch the image bytes.",
                "type": "string"
              },
              "mime": {
                "description": "Image MIME type.",
                "type": "string"
              },
              "size": {
                "description": "Image size in bytes.",
                "type": [
                  "integer",
                  "null"
                ]
              },
              "position": {
                "description": "0-based position in the gallery.",
                "type": "integer"
              }
            },
            "type": "object",
            "required": [
              "url"
            ]
          },
          "type": "array"
        },
        "imageUrl": {
          "description": "Legacy convenience: URL of the first image. Present only when hasImage is true.",
          "type": "string"
        },
        "imageMime": {
          "description": "Legacy convenience: MIME type of the first image.",
          "type": "string"
        },
        "imageSize": {
          "description": "Legacy convenience: size of the first image in bytes.",
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "type": "object",
      "required": [
        "id",
        "device",
        "edited",
        "hasImage",
        "imageCount"
      ]
    }
  },
  "required": [
    "code",
    "url",
    "item"
  ]
}

Post one or more images (PNG, JPEG, GIF, or WEBP) to a Clippy room so they appear on every device watching it, optionally with a text caption. Pass each image as a base64 string or a data: URI. The room is created if it does not exist. Subscribed devices get a push notification. Returns the stored item, including direct URLs to fetch each image.

{
  "type": "object",
  "properties": {
    "room": {
      "description": "The 6-character room code (or a Clippy share URL / #CODE link). The room is created if new.",
      "type": "string"
    },
    "images": {
      "description": "One or more images, each a base64-encoded PNG/JPEG/GIF/WEBP or a data: URI (e.g. \"data:image/png;base64,iVBOR...\"). Up to 10 images, 10 MB each.",
      "minItems": 1,
      "maxItems": 10,
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "text": {
      "description": "Optional caption to store alongside the image(s). Up to 200,000 characters.",
      "type": "string"
    },
    "device": {
      "description": "Optional short label for who is posting (max 64 chars). Defaults to \"AI Agent\".",
      "type": "string"
    },
    "password": {
      "description": "Required only if the room is password-protected and you are not using owner_token.",
      "type": "string"
    },
    "owner_token": {
      "description": "Optional. The room owner_token; bypasses the password on a locked room.",
      "type": "string"
    }
  },
  "required": [
    "room",
    "images"
  ]
}

{
  "type": "object",
  "properties": {
    "code": {
      "description": "The room code the image was stored in.",
      "type": "string"
    },
    "url": {
      "description": "Human-shareable URL that opens the room on any device.",
      "type": "string"
    },
    "item": {
      "description": "The stored item, including image URLs.",
      "properties": {
        "id": {
          "description": "The item id (UUID).",
          "type": "string"
        },
        "text": {
          "description": "The text content, or null for image-only items.",
          "type": [
            "string",
            "null"
          ]
        },
        "device": {
          "description": "Label for who posted the item.",
          "type": "string"
        },
        "createdAt": {
          "description": "Creation time, Unix milliseconds.",
          "type": [
            "integer",
            "null"
          ]
        },
        "updatedAt": {
          "description": "Last-update time, Unix milliseconds.",
          "type": [
            "integer",
            "null"
          ]
        },
        "edited": {
          "description": "Whether the item was edited after it was created.",
          "type": "boolean"
        },
        "hasImage": {
          "description": "Whether the item has one or more images.",
          "type": "boolean"
        },
        "imageCount": {
          "description": "Number of images attached to the item.",
          "type": "integer"
        },
        "images": {
          "description": "Attached images, ordered by position. Present only when hasImage is true.",
          "items": {
            "properties": {
              "url": {
                "description": "Absolute URL to fetch the image bytes.",
                "type": "string"
              },
              "mime": {
                "description": "Image MIME type.",
                "type": "string"
              },
              "size": {
                "description": "Image size in bytes.",
                "type": [
                  "integer",
                  "null"
                ]
              },
              "position": {
                "description": "0-based position in the gallery.",
                "type": "integer"
              }
            },
            "type": "object",
            "required": [
              "url"
            ]
          },
          "type": "array"
        },
        "imageUrl": {
          "description": "Legacy convenience: URL of the first image. Present only when hasImage is true.",
          "type": "string"
        },
        "imageMime": {
          "description": "Legacy convenience: MIME type of the first image.",
          "type": "string"
        },
        "imageSize": {
          "description": "Legacy convenience: size of the first image in bytes.",
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "type": "object",
      "required": [
        "id",
        "device",
        "edited",
        "hasImage",
        "imageCount"
      ]
    }
  },
  "required": [
    "code",
    "url",
    "item"
  ]
}

Read the items in a Clippy room (newest first). Use this to pick up text a user or another agent left for you, or to see what is currently in a shared room. Pass `since` (a millisecond timestamp from a previous call) to fetch only items added after that point. Image items include direct image URLs.

{
  "type": "object",
  "properties": {
    "room": {
      "description": "The 6-character room code (or a Clippy share URL / #CODE link).",
      "type": "string"
    },
    "since": {
      "description": "Optional. Return only items created strictly after this Unix timestamp in milliseconds. Use the `now` value from a previous call to poll incrementally.",
      "type": "integer"
    },
    "limit": {
      "description": "Optional. Maximum number of items to return (1–100). Defaults to 100.",
      "type": "integer"
    },
    "password": {
      "description": "Required only if the room is password-protected and you are not using owner_token.",
      "type": "string"
    },
    "owner_token": {
      "description": "Optional. The room owner_token; bypasses the password on a locked room.",
      "type": "string"
    }
  },
  "required": [
    "room"
  ]
}

{
  "type": "object",
  "properties": {
    "code": {
      "description": "The room code that was read.",
      "type": "string"
    },
    "locked": {
      "description": "Whether the room is password-protected.",
      "type": "boolean"
    },
    "count": {
      "description": "Number of items returned.",
      "type": "integer"
    },
    "items": {
      "description": "The matching items, newest first.",
      "items": {
        "properties": {
          "id": {
            "description": "The item id (UUID).",
            "type": "string"
          },
          "text": {
            "description": "The text content, or null for image-only items.",
            "type": [
              "string",
              "null"
            ]
          },
          "device": {
            "description": "Label for who posted the item.",
            "type": "string"
          },
          "createdAt": {
            "description": "Creation time, Unix milliseconds.",
            "type": [
              "integer",
              "null"
            ]
          },
          "updatedAt": {
            "description": "Last-update time, Unix milliseconds.",
            "type": [
              "integer",
              "null"
            ]
          },
          "edited": {
            "description": "Whether the item was edited after it was created.",
            "type": "boolean"
          },
          "hasImage": {
            "description": "Whether the item has one or more images.",
            "type": "boolean"
          },
          "imageCount": {
            "description": "Number of images attached to the item.",
            "type": "integer"
          },
          "images": {
            "description": "Attached images, ordered by position. Present only when hasImage is true.",
            "items": {
              "properties": {
                "url": {
                  "description": "Absolute URL to fetch the image bytes.",
                  "type": "string"
                },
                "mime": {
                  "description": "Image MIME type.",
                  "type": "string"
                },
                "size": {
                  "description": "Image size in bytes.",
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "position": {
                  "description": "0-based position in the gallery.",
                  "type": "integer"
                }
              },
              "type": "object",
              "required": [
                "url"
              ]
            },
            "type": "array"
          },
          "imageUrl": {
            "description": "Legacy convenience: URL of the first image. Present only when hasImage is true.",
            "type": "string"
          },
          "imageMime": {
            "description": "Legacy convenience: MIME type of the first image.",
            "type": "string"
          },
          "imageSize": {
            "description": "Legacy convenience: size of the first image in bytes.",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "type": "object",
        "required": [
          "id",
          "device",
          "edited",
          "hasImage",
          "imageCount"
        ]
      },
      "type": "array"
    },
    "now": {
      "description": "Server time in Unix milliseconds; pass as `since` next call to poll incrementally.",
      "type": "integer"
    }
  },
  "required": [
    "code",
    "locked",
    "count",
    "items",
    "now"
  ]
}

Check whether a Clippy room exists, whether it is password-protected, and how many items it holds — without reading the contents. Handy before deciding to read or write, or to confirm a code a user gave you is valid.

{
  "type": "object",
  "properties": {
    "room": {
      "description": "The 6-character room code (or a Clippy share URL / #CODE link).",
      "type": "string"
    }
  },
  "required": [
    "room"
  ]
}

{
  "type": "object",
  "properties": {
    "code": {
      "description": "The room code that was checked.",
      "type": "string"
    },
    "exists": {
      "description": "Whether the room currently exists.",
      "type": "boolean"
    },
    "locked": {
      "description": "Whether the room is password-protected.",
      "type": "boolean"
    },
    "itemCount": {
      "description": "Number of items currently in the room.",
      "type": "integer"
    },
    "url": {
      "description": "Human-shareable URL for the room.",
      "type": "string"
    }
  },
  "required": [
    "code",
    "exists",
    "locked",
    "itemCount",
    "url"
  ]
}

Edit the text of an existing item in a Clippy room, identified by its item id (the `id` field returned by store-item / list-items). Image bytes are immutable; this changes only the text.

{
  "type": "object",
  "properties": {
    "room": {
      "description": "The 6-character room code (or a Clippy share URL / #CODE link).",
      "type": "string"
    },
    "item_id": {
      "description": "The item id (UUID) to edit, as returned in the `id` field of a stored/listed item.",
      "type": "string"
    },
    "text": {
      "description": "The new text. For a text-only item this cannot be empty — delete it instead.",
      "type": "string"
    },
    "password": {
      "description": "Required only if the room is password-protected and you are not using owner_token.",
      "type": "string"
    },
    "owner_token": {
      "description": "Optional. The room owner_token; bypasses the password on a locked room.",
      "type": "string"
    }
  },
  "required": [
    "room",
    "item_id",
    "text"
  ]
}

{
  "type": "object",
  "properties": {
    "code": {
      "description": "The room code containing the item.",
      "type": "string"
    },
    "item": {
      "description": "The updated item.",
      "properties": {
        "id": {
          "description": "The item id (UUID).",
          "type": "string"
        },
        "text": {
          "description": "The text content, or null for image-only items.",
          "type": [
            "string",
            "null"
          ]
        },
        "device": {
          "description": "Label for who posted the item.",
          "type": "string"
        },
        "createdAt": {
          "description": "Creation time, Unix milliseconds.",
          "type": [
            "integer",
            "null"
          ]
        },
        "updatedAt": {
          "description": "Last-update time, Unix milliseconds.",
          "type": [
            "integer",
            "null"
          ]
        },
        "edited": {
          "description": "Whether the item was edited after it was created.",
          "type": "boolean"
        },
        "hasImage": {
          "description": "Whether the item has one or more images.",
          "type": "boolean"
        },
        "imageCount": {
          "description": "Number of images attached to the item.",
          "type": "integer"
        },
        "images": {
          "description": "Attached images, ordered by position. Present only when hasImage is true.",
          "items": {
            "properties": {
              "url": {
                "description": "Absolute URL to fetch the image bytes.",
                "type": "string"
              },
              "mime": {
                "description": "Image MIME type.",
                "type": "string"
              },
              "size": {
                "description": "Image size in bytes.",
                "type": [
                  "integer",
                  "null"
                ]
              },
              "position": {
                "description": "0-based position in the gallery.",
                "type": "integer"
              }
            },
            "type": "object",
            "required": [
              "url"
            ]
          },
          "type": "array"
        },
        "imageUrl": {
          "description": "Legacy convenience: URL of the first image. Present only when hasImage is true.",
          "type": "string"
        },
        "imageMime": {
          "description": "Legacy convenience: MIME type of the first image.",
          "type": "string"
        },
        "imageSize": {
          "description": "Legacy convenience: size of the first image in bytes.",
          "type": [
            "integer",
            "null"
          ]
        }
      },
      "type": "object",
      "required": [
        "id",
        "device",
        "edited",
        "hasImage",
        "imageCount"
      ]
    }
  },
  "required": [
    "code",
    "item"
  ]
}

Delete a single item from a Clippy room by its item id (the `id` returned by store-item / list-items). Any images attached to the item are removed too. This cannot be undone.

{
  "type": "object",
  "properties": {
    "room": {
      "description": "The 6-character room code (or a Clippy share URL / #CODE link).",
      "type": "string"
    },
    "item_id": {
      "description": "The item id (UUID) to delete.",
      "type": "string"
    },
    "password": {
      "description": "Required only if the room is password-protected and you are not using owner_token.",
      "type": "string"
    },
    "owner_token": {
      "description": "Optional. The room owner_token; bypasses the password on a locked room.",
      "type": "string"
    }
  },
  "required": [
    "room",
    "item_id"
  ]
}

{
  "type": "object",
  "properties": {
    "code": {
      "description": "The room code that was targeted.",
      "type": "string"
    },
    "deleted": {
      "description": "Whether an item was actually deleted (false if it did not exist).",
      "type": "boolean"
    }
  },
  "required": [
    "code",
    "deleted"
  ]
}

Delete ALL items in a Clippy room (and their images). Use with care — this wipes everything shared in the room and cannot be undone. The room itself continues to exist and can be reused.

{
  "type": "object",
  "properties": {
    "room": {
      "description": "The 6-character room code (or a Clippy share URL / #CODE link).",
      "type": "string"
    },
    "password": {
      "description": "Required only if the room is password-protected and you are not using owner_token.",
      "type": "string"
    },
    "owner_token": {
      "description": "Optional. The room owner_token; bypasses the password on a locked room.",
      "type": "string"
    }
  },
  "required": [
    "room"
  ]
}

{
  "type": "object",
  "properties": {
    "code": {
      "description": "The room code that was cleared.",
      "type": "string"
    },
    "cleared": {
      "description": "Number of items that were deleted.",
      "type": "integer"
    }
  },
  "required": [
    "code",
    "cleared"
  ]
}

Lock or unlock a Clippy room. Requires the room owner_token (returned by create-room). Pass a password to lock the room; pass an empty password to remove the lock. Only the owner can change this.

{
  "type": "object",
  "properties": {
    "room": {
      "description": "The 6-character room code (or a Clippy share URL / #CODE link).",
      "type": "string"
    },
    "owner_token": {
      "description": "The room owner_token proving you own this room. Required.",
      "type": "string"
    },
    "password": {
      "description": "The new password to lock the room with. Pass an empty string to remove the password and make the room open.",
      "type": "string"
    }
  },
  "required": [
    "room",
    "owner_token"
  ]
}

{
  "type": "object",
  "properties": {
    "code": {
      "description": "The room code whose lock state changed.",
      "type": "string"
    },
    "locked": {
      "description": "Whether the room is now password-protected.",
      "type": "boolean"
    }
  },
  "required": [
    "code",
    "locked"
  ]
}