Workflowy Nodes API

openapi: 3.1.0
info:
  title: Workflowy Nodes API
  description: Official Workflowy REST API for reading and writing Workflowy data programmatically. A node is the fundamental unit of content in Workflowy - each node is a single bullet point that can contain text, have child nodes, and be organized hierarchically. Targets provide quick access to specific nodes, including system targets (like "inbox") and user-defined shortcuts. This OpenAPI document was generated by API Evangelist from the official API reference at https://workflowy.com/api-reference/ - Workflowy does not publish its own machine-readable spec.
  version: v1
  contact:
    name: Workflowy
    url: https://workflowy.com/api-reference/
servers:
- url: https://workflowy.com/api/v1
  description: Production
security:
- apiKey: []
tags:
- name: Nodes
  description: Create, read, update, move, complete, and delete outline nodes.
paths:
  /nodes:
    post:
      operationId: createNode
      tags:
      - Nodes
      summary: Create a node
      description: Creates a new node under the given parent. Calendar nodes are created on demand if they don't exist yet. Markdown in `name` is parsed into inline HTML and layout modes; multiline `name` text creates child nodes (`\n` joins into a space, `\n\n` creates separate children).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                parent_id:
                  $ref: '#/components/schemas/ParentTarget'
                name:
                  type: string
                  description: The text content of the new node. Markdown inline styles (bold, italic, strikethrough, code, links, dates) and layout prefixes ("#", "##", "###", "-", "- [ ]", "- [x]", code fence, ">") are parsed.
                layoutMode:
                  $ref: '#/components/schemas/LayoutMode'
                note:
                  type: string
                  description: Additional note content shown below the main text.
                position:
                  type: string
                  enum:
                  - top
                  - bottom
                  default: top
                  description: Where to place the new node.
            example:
              parent_id: inbox
              name: Hello API
              position: top
      responses:
        '200':
          description: Node created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  item_id:
                    type: string
              example:
                item_id: 5b401959-4740-4e1a-905a-62a961daa8c9
    get:
      operationId: listNodes
      tags:
      - Nodes
      summary: List nodes
      description: Returns a list of child nodes for a given parent. Nodes are returned unordered - sort them yourself based on the `priority` field. Calendar keys return 404 if the node hasn't been created yet; use Create or Move to materialize it first.
      parameters:
      - name: parent_id
        in: query
        description: Whose children to list. Accepts a full node id, 12-character short id, node URL, a shortcut key, "None" (root), "inbox", or calendar targets (calendar, today, tomorrow, next_week, YYYY, YYYY-MM, YYYY-MM-DD).
        schema:
          type: string
        example: inbox
      responses:
        '200':
          description: Child nodes (unordered).
          content:
            application/json:
              schema:
                type: object
                properties:
                  nodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Node'
        '404':
          description: Calendar key target that has not been created yet.
  /nodes/{id}:
    post:
      operationId: updateNode
      tags:
      - Nodes
      summary: Update a node
      description: Updates the specified node by setting the values of the parameters passed. Any parameters not provided are left unchanged. Markdown in `name` is parsed into inline HTML and layout modes.
      parameters:
      - $ref: '#/components/parameters/nodeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                layoutMode:
                  $ref: '#/components/schemas/LayoutMode'
                note:
                  type: string
            example:
              name: Updated node title
      responses:
        '200':
          $ref: '#/components/responses/StatusOk'
    get:
      operationId: getNode
      tags:
      - Nodes
      summary: Retrieve a node
      description: Retrieves the details of an existing node. Supply either the full node ID, short node ID, or an existing calendar target (calendar, today, tomorrow, next_week, YYYY, YYYY-MM, YYYY-MM-DD). Calendar targets resolve existing calendar structure nodes and do not create missing nodes.
      parameters:
      - $ref: '#/components/parameters/nodeId'
      responses:
        '200':
          description: The node.
          content:
            application/json:
              schema:
                type: object
                properties:
                  node:
                    $ref: '#/components/schemas/Node'
    delete:
      operationId: deleteNode
      tags:
      - Nodes
      summary: Delete a node
      description: Permanently deletes a node. This cannot be undone.
      parameters:
      - $ref: '#/components/parameters/nodeId'
      responses:
        '200':
          $ref: '#/components/responses/StatusOk'
  /nodes/{id}/move:
    post:
      operationId: moveNode
      tags:
      - Nodes
      summary: Move a node
      description: Relocates a node to a different parent. Calendar nodes are created on demand if they don't exist yet.
      parameters:
      - $ref: '#/components/parameters/nodeId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                parent_id:
                  $ref: '#/components/schemas/ParentTarget'
                position:
                  type: string
                  enum:
                  - top
                  - bottom
                  default: top
            example:
              parent_id: inbox
              position: top
      responses:
        '200':
          $ref: '#/components/responses/StatusOk'
  /nodes/{id}/complete:
    post:
      operationId: completeNode
      tags:
      - Nodes
      summary: Complete a node
      description: Marks a node as completed. Sets the completion timestamp and updates the node's status.
      parameters:
      - $ref: '#/components/parameters/nodeId'
      responses:
        '200':
          $ref: '#/components/responses/StatusOk'
  /nodes/{id}/uncomplete:
    post:
      operationId: uncompleteNode
      tags:
      - Nodes
      summary: Uncomplete a node
      description: Marks a node as not completed. Removes the completion timestamp and updates the node's status.
      parameters:
      - $ref: '#/components/parameters/nodeId'
      responses:
        '200':
          $ref: '#/components/responses/StatusOk'
  /nodes-export:
    get:
      operationId: exportNodes
      tags:
      - Nodes
      summary: Export all nodes
      description: 'Returns all of the user''s nodes as a flat list. Each node includes its `parent_id` field to reconstruct the hierarchy. Nodes are returned unordered - build the tree yourself from `parent_id` and `priority`. Rate limit: 1 request per minute due to potentially large response size.'
      responses:
        '200':
          description: All nodes as a flat list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  nodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExportNode'
components:
  schemas:
    ParentTarget:
      type: string
      description: A parent reference - full node id, 12-character short id, node URL, a user-defined shortcut key, "None" (root), "inbox", or calendar targets ("calendar", "today", "tomorrow", "next_week", "YYYY", "YYYY-MM", "YYYY-MM-DD").
      example: inbox
    ExportNode:
      allOf:
      - $ref: '#/components/schemas/Node'
      - type: object
        properties:
          completed:
            type: boolean
            description: Whether the node is completed (export endpoint only).
    Node:
      type: object
      description: A node is a single bullet point that can contain text, have child nodes, and be organized hierarchically.
      properties:
        id:
          type: string
          description: Unique identifier of the node.
        parent_id:
          type:
          - string
          - 'null'
          description: Unique identifier of the parent node. `null` for top-level nodes.
        name:
          type: string
          description: The text content of the node. Supports inline HTML tags <b>, <i>, <s>, <code>, <a href="">.
        note:
          type:
          - string
          - 'null'
          description: Additional note content shown below the main text.
        priority:
          type: number
          description: Sort order of the node among its siblings. Lower values appear first.
        data:
          type: object
          properties:
            layoutMode:
              $ref: '#/components/schemas/LayoutMode'
        createdAt:
          type: number
          description: Unix timestamp when the node was created.
        modifiedAt:
          type: number
          description: Unix timestamp when the node was last modified.
        completedAt:
          type:
          - number
          - 'null'
          description: Unix timestamp when the node was completed. `null` if not completed.
      example:
        id: 6ed4b9ca-256c-bf2e-bd70-d8754237b505
        parent_id: 5b401959-4740-4e1a-905a-62a961daa8c9
        name: This is a test outline for API examples
        note: null
        priority: 200
        data:
          layoutMode: bullets
        createdAt: 1753120779
        modifiedAt: 1753120850
        completedAt: null
    LayoutMode:
      type: string
      description: Display mode of the node.
      enum:
      - bullets
      - todo
      - h1
      - h2
      - h3
      - code-block
      - quote-block
  parameters:
    nodeId:
      name: id
      in: path
      required: true
      description: The node ID, 12-character short ID, or calendar target.
      schema:
        type: string
  responses:
    StatusOk:
      description: Operation succeeded.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
          example:
            status: ok
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Workflowy API key sent as a bearer token in the Authorization header. Generate a key at https://workflowy.com/api-key/.
x-generated: '2026-07-21'
x-method: generated
x-source: https://workflowy.com/api-reference/ (verbatim markdown at https://workflowy.com/api-reference.md)