lucid.page

Publish Markdown as a beautifully typeset page and receive its https://lucid.page/<slug> URL. Works anonymously; with an lp_ API key the page is owned by the account and can be updated later. Anonymous publishes return a one-time claim_token — hand your human the claim link https://lucid.page/claim?slug=<slug>&token=<claim_token> so they can claim the page into their account (agents: POST /api/docs/<slug>/claim).

{
  "type": "object",
  "properties": {
    "markdown": {
      "type": "string",
      "description": "The Markdown source to publish (max 1 MB)."
    },
    "title": {
      "type": "string",
      "description": "Optional display title."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ],
      "description": "Defaults to unlisted. Private requires an lp_ API key."
    },
    "ttl": {
      "type": "integer",
      "description": "Lifetime in seconds (min 60). Omit for a page that never expires."
    }
  },
  "required": [
    "markdown"
  ]
}

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "description": "The live page URL."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ]
    },
    "expires_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "ISO timestamp, or null when the page never expires"
    },
    "claim_token": {
      "type": "string",
      "description": "One-time ownership token (anonymous publishes only). A human claims the page at https://lucid.page/claim?slug=<slug>&token=<claim_token>; agents claim with POST /api/docs/<slug>/claim."
    }
  },
  "required": [
    "slug",
    "url",
    "visibility",
    "expires_at"
  ]
}

Replace the Markdown of a page you own (requires an lp_ API key). The URL stays the same; every update is kept as a revision. Pass expected_version (from get_doc) to guard against overwriting someone else's changes — a conflict returns 409 with current_version.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The document slug — the path part of its https://lucid.page/<slug> URL."
    },
    "markdown": {
      "type": "string",
      "description": "The new Markdown source (max 1 MB)."
    },
    "title": {
      "type": "string",
      "description": "Optional new title; omit to keep the current one."
    },
    "expected_version": {
      "type": "integer",
      "description": "Optional optimistic-lock guard: the version you last read. Saves only if it still matches."
    }
  },
  "required": [
    "slug",
    "markdown"
  ]
}

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "revision_hash": {
      "type": "string",
      "description": "Content hash of the new revision"
    },
    "visibility": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "version": {
      "type": "integer",
      "description": "Monotonic save counter; pass as expected_version next time"
    }
  },
  "required": [
    "slug",
    "revision_hash",
    "visibility",
    "url"
  ]
}

Fetch the canonical Markdown source of a page. Public and unlisted pages are open to anyone; private pages require the owner's lp_ API key.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The document slug — the path part of its https://lucid.page/<slug> URL."
    }
  },
  "required": [
    "slug"
  ]
}

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "markdown": {
      "type": "string",
      "description": "The canonical Markdown source of the page"
    },
    "version": {
      "type": "integer",
      "description": "Current version; pass as expected_version to update_doc"
    }
  },
  "required": [
    "slug",
    "markdown"
  ]
}

List the documents owned by the authenticated account (requires an lp_ API key), newest first, with cursor pagination.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Max documents to return (1-200, default 50)."
    },
    "cursor": {
      "type": "string",
      "description": "The nextCursor value from a previous call."
    }
  }
}

{
  "type": "object",
  "properties": {
    "docs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "visibility": {
            "type": "string"
          },
          "view_count": {
            "type": "integer"
          },
          "updated_at": {
            "type": "string"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "slug"
        ]
      }
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass as the cursor argument for the next page; null when the listing is exhausted"
    }
  },
  "required": [
    "docs",
    "nextCursor"
  ]
}

Permanently delete a page you own (requires an lp_ API key). The URL stops serving immediately and cannot be recovered.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "The document slug — the path part of its https://lucid.page/<slug> URL."
    }
  },
  "required": [
    "slug"
  ]
}

{
  "type": "object",
  "properties": {
    "deleted": {
      "type": "string",
      "description": "Slug of the deleted page"
    }
  },
  "required": [
    "deleted"
  ]
}

Create a binder: an ordered list of lucid.page pages and external links, each with an optional note, served at https://lucid.page/b/<slug> (requires an lp_ API key). Up to 100 binders per account and 500 items per binder. Public binders with at least one visible item are indexable.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "The binder title (1-120 characters)."
    },
    "description": {
      "type": "string",
      "description": "Optional plain-text description; blank lines start a new paragraph."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ],
      "description": "Defaults to unlisted."
    },
    "items": {
      "type": "array",
      "description": "Optional initial items, in order. Each needs exactly one of slug or url.",
      "items": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "A lucid.page page slug: one of your own pages, or anyone's public or unlisted page."
          },
          "url": {
            "type": "string",
            "description": "An http(s) link. Links to lucid.page pages are stored as those pages."
          },
          "title": {
            "type": "string",
            "description": "Optional display title for a link."
          },
          "note": {
            "type": "string",
            "description": "Optional note shown with the item."
          }
        }
      }
    }
  },
  "required": [
    "title"
  ]
}

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "description": "The binder page URL, https://lucid.page/b/<slug>"
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ]
    },
    "item_count": {
      "type": "integer"
    }
  },
  "required": [
    "slug",
    "url",
    "visibility",
    "item_count"
  ]
}

Append one item to a binder you own (requires an lp_ API key). Pass exactly one of slug (a lucid.page page) or url (any http(s) link), plus an optional title (links only) and note.

{
  "type": "object",
  "properties": {
    "binder": {
      "type": "string",
      "description": "The binder slug."
    },
    "slug": {
      "type": "string",
      "description": "A lucid.page page slug: one of your own pages, or anyone's public or unlisted page."
    },
    "url": {
      "type": "string",
      "description": "An http(s) link. Links to lucid.page pages are stored as those pages."
    },
    "title": {
      "type": "string",
      "description": "Optional display title for a link."
    },
    "note": {
      "type": "string",
      "description": "Optional note shown with the item."
    }
  },
  "required": [
    "binder"
  ]
}

{
  "type": "object",
  "properties": {
    "binder": {
      "type": "string",
      "description": "The binder slug"
    },
    "url": {
      "type": "string",
      "description": "The binder page URL"
    },
    "item_id": {
      "type": "string",
      "description": "Id of the added item"
    },
    "item_count": {
      "type": "integer"
    }
  },
  "required": [
    "binder",
    "url",
    "item_id",
    "item_count"
  ]
}

Show the lucid.page account matrix (anonymous vs lp_ API key) and, when a key is present, the caller's current plan status.

{
  "type": "object",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "plans": {
      "type": "object",
      "description": "Account matrix: anonymous, with_api_key, pro_team"
    },
    "account": {
      "type": "object",
      "properties": {
        "accountId": {
          "type": "string"
        },
        "plan": {
          "type": "string",
          "description": "free | pro | team"
        },
        "activeSubscription": {
          "type": "boolean"
        }
      },
      "required": [
        "accountId",
        "plan",
        "activeSubscription"
      ],
      "description": "Present when an lp_ API key was supplied"
    }
  },
  "required": [
    "plans"
  ]
}