Plans & Playbooks

list_plans

List plans visible to the authenticated user with filters and pagination.

Parameters

Name	Type	Required	Default	Description
`stage`	`array of string`	No	—	Array of stage enum values. Use UNDERSCORE form In_Process. Allowed: Suggested, Accepted, In_Process, Complete, Dismissed. Omit for all stages. Note: only the first array element is honored currently — pass single-value arrays to be safe.
`source`	`array of string`	No	—	Array of source enum values: user_added, cora_proactive, cora_requested, workflow, playbook. Note: only the first array element is honored currently — pass single-value arrays to be safe.
`project_id`	`string`	No	—	Filter to plans associated with this project (project UUID string).
`category_id`	`integer`	No	—	Filter to plans in this content category (integer ID). Omit (or pass 0/null) for NO category filter — all plans return, including uncategorized ones.
`assignee_scope`	`string`	No	—	Whose plans to return. "me" (default — plans assigned to you) \| "created_by_me" (plans you created) \| "all_visible" (all plans visible to your team).
`due_before`	`string`	No	—	ISO date YYYY-MM-DD. Returns plans with due_date <= due_before. Note: does not apply yet.
`due_after`	`string`	No	—	ISO date YYYY-MM-DD. Returns plans with due_date >= due_after. Note: does not apply yet.
`search_text`	`string`	No	—	Substring match on plan title (case-insensitive). Note: does not apply yet.
`sort`	`string`	No	—	Sort order: "due_asc_nulls_last" (default — best for action planning) \| "created_desc" (newest first).
`page`	`integer`	No	—	Page number (default 1).
`per_page`	`integer`	No	—	Items per page (default 20, max 100).

Input Schema

{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "description": "Page number (default 1)."
    },
    "sort": {
      "type": "string",
      "description": "Sort order: \"due_asc_nulls_last\" (default — best for action planning) | \"created_desc\" (newest first)."
    },
    "stage": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of stage enum values. Use UNDERSCORE form In_Process. Allowed: Suggested, Accepted, In_Process, Complete, Dismissed. Omit for all stages. Note: only the first array element is honored currently — pass single-value arrays to be safe."
    },
    "source": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Array of source enum values: user_added, cora_proactive, cora_requested, workflow, playbook. Note: only the first array element is honored currently — pass single-value arrays to be safe."
    },
    "per_page": {
      "type": "integer",
      "description": "Items per page (default 20, max 100)."
    },
    "due_after": {
      "type": "string",
      "description": "ISO date YYYY-MM-DD. Returns plans with due_date >= due_after. Note: does not apply yet."
    },
    "due_before": {
      "type": "string",
      "description": "ISO date YYYY-MM-DD. Returns plans with due_date <= due_before. Note: does not apply yet."
    },
    "project_id": {
      "type": "string",
      "description": "Filter to plans associated with this project (project UUID string)."
    },
    "category_id": {
      "type": "integer",
      "description": "Filter to plans in this content category (integer ID). Omit (or pass 0/null) for NO category filter — all plans return, including uncategorized ones."
    },
    "search_text": {
      "type": "string",
      "description": "Substring match on plan title (case-insensitive). Note: does not apply yet."
    },
    "assignee_scope": {
      "type": "string",
      "description": "Whose plans to return. \"me\" (default — plans assigned to you) | \"created_by_me\" (plans you created) | \"all_visible\" (all plans visible to your team)."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "stage": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "due_date": {
            "type": [
              "string",
              "null"
            ]
          },
          "link_url": {
            "type": "string",
            "format": "uri"
          },
          "plan_uuid": {
            "type": "string",
            "format": "uuid"
          },
          "created_at": {
            "type": "integer"
          },
          "created_by": {
            "type": "integer"
          },
          "updated_at": {
            "type": "integer"
          },
          "assigned_to": {
            "type": "integer"
          },
          "produced_content_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "description": "Array of plan summary objects. Each item: plan_uuid, link_url (shareable deep-link opening this plan's overlay), title, stage, source, assigned_to, created_by, due_date, produced_content_id, created_at, updated_at."
    },
    "curPage": {
      "type": "integer"
    },
    "nextPage": {
      "type": [
        "integer",
        "null"
      ]
    },
    "prevPage": {
      "type": [
        "integer",
        "null"
      ]
    },
    "itemsTotal": {
      "type": "integer"
    }
  },
  "description": "Paginated plan summary results."
}

Instructions

Returns a paginated list of plans visible to the authenticated user. Use filters to narrow results by stage, source, project, or category.

Stage filter values: Use UNDERSCORE form — In_Process (not In Process). Allowed: Suggested, Accepted, In_Process, Complete, Dismissed. Note: only the first array element is honored currently.

Source filter values: user_added, cora_proactive, cora_requested, workflow, playbook. Note: only the first array element is honored currently.

Assignee scope: me (default — plans assigned to you), created_by_me (plans you created), all_visible (all plans visible to you).

Sorting: due_asc_nulls_last (default — soonest due date first, nulls last) or created_desc (newest first).

Pagination: Use page and per_page (max 100). The response includes nextPage and prevPage for traversal.

Note: due_before, due_after, and search_text filters are accepted but do not apply yet.

Links: present link_url to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.