Plans & Playbooks

create_plan

Create a new plan in the authenticated user's active team.

Parameters

Name	Type	Required	Default	Description
`title`	`string`	Yes	—	Required. The one-line summary of the content intent (1-200 chars).
`description`	`string`	No	—	Optional free-text description of what this plan is for.
`due_date`	`string`	No	—	Optional target completion date. ISO 8601 date string YYYY-MM-DD.
`prompt`	`string`	No	—	The actual content prompt — pre-populates the content creation form when the plan is acted on.
`blueprint_id`	`string`	No	—	Blueprint UUID (from list_blueprints) or integer blueprint id. UUIDs are resolved server-side; unknown UUIDs return InputError.
`project_id`	`string`	No	—	Project UUID string to associate with this plan.
`category_id`	`integer`	No	—	Content category integer ID.
`reference_document_ids`	`array of string`	No	—	Array of content UUID strings to associate as reference material.
`context_collection_ids`	`array of integer`	No	—	Array of integer collection IDs to pre-attach.
`targeting_dimension_ids`	`array of integer`	No	—	Array of integer dimension option IDs to pre-attach.
`source`	`string`	No	—	Plan source. Default cora_requested for Marcora interactive callers. The cora_* values are legacy wire names that predate the Marcora rename and are unchanged — send them exactly as written. Allowed: user_added, cora_proactive, cora_requested, workflow, playbook. Immutable after creation.
`source_metadata`	`object`	No	—	Optional. Shape varies by source: {cora_session_id, cora_message_snippet} for cora_proactive; {workflow_template_id, workflow_run_id, workflow_name, run_timestamp} for workflow. Immutable after creation.
`assigned_to`	`integer`	No	—	Optional integer user ID to assign this plan to. Defaults to creator. Must be a current team member.
`visibility`	`string`	No	—	Optional. Defaults to "private" (creator-only ideas queue). "team" makes the plan visible to all active teammates. Assigning to someone other than the calling user auto-promotes to "team".
`plan_uuid`	`string`	No	—	Optional client-supplied UUIDv4 for optimistic creates. Server validates format + uniqueness. Server generates if omitted.

Input Schema

{
  "type": "object",
  "required": [
    "title"
  ],
  "properties": {
    "title": {
      "type": "string",
      "description": "Required. The one-line summary of the content intent (1-200 chars)."
    },
    "prompt": {
      "type": "string",
      "description": "The actual content prompt — pre-populates the content creation form when the plan is acted on."
    },
    "source": {
      "type": "string",
      "description": "Plan source. Default cora_requested for Marcora interactive callers. The cora_* values are legacy wire names that predate the Marcora rename and are unchanged — send them exactly as written. Allowed: user_added, cora_proactive, cora_requested, workflow, playbook. Immutable after creation."
    },
    "due_date": {
      "type": "string",
      "description": "Optional target completion date. ISO 8601 date string YYYY-MM-DD."
    },
    "plan_uuid": {
      "type": "string",
      "description": "Optional client-supplied UUIDv4 for optimistic creates. Server validates format + uniqueness. Server generates if omitted."
    },
    "project_id": {
      "type": "string",
      "description": "Project UUID string to associate with this plan."
    },
    "visibility": {
      "enum": [
        "private",
        "team"
      ],
      "type": "string",
      "description": "Optional. Defaults to \"private\" (creator-only ideas queue). \"team\" makes the plan visible to all active teammates. Assigning to someone other than the calling user auto-promotes to \"team\"."
    },
    "assigned_to": {
      "type": "integer",
      "description": "Optional integer user ID to assign this plan to. Defaults to creator. Must be a current team member."
    },
    "category_id": {
      "type": "integer",
      "description": "Content category integer ID."
    },
    "description": {
      "type": "string",
      "description": "Optional free-text description of what this plan is for."
    },
    "blueprint_id": {
      "type": "string",
      "description": "Blueprint UUID (from list_blueprints) or integer blueprint id. UUIDs are resolved server-side; unknown UUIDs return InputError."
    },
    "source_metadata": {
      "description": "Optional. Shape varies by source: {cora_session_id, cora_message_snippet} for cora_proactive; {workflow_template_id, workflow_run_id, workflow_name, run_timestamp} for workflow. Immutable after creation."
    },
    "context_collection_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Array of integer collection IDs to pre-attach."
    },
    "reference_document_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Array of content UUID strings to associate as reference material."
    },
    "targeting_dimension_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Array of integer dimension option IDs to pre-attach."
    }
  }
}

Output Schema

{
  "type": "object",
  "required": [
    "plan_uuid",
    "id",
    "team_id",
    "created_by",
    "assigned_to",
    "stage",
    "source",
    "title",
    "created_at",
    "updated_at",
    "link_url"
  ],
  "properties": {
    "id": {
      "type": "integer",
      "description": "Internal integer PK; not exposed externally."
    },
    "stage": {
      "enum": [
        "Suggested",
        "Accepted",
        "In_Process",
        "Complete",
        "Dismissed"
      ],
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "prompt": {
      "type": [
        "string",
        "null"
      ]
    },
    "source": {
      "type": "string"
    },
    "team_id": {
      "type": "integer"
    },
    "due_date": {
      "type": [
        "string",
        "null"
      ]
    },
    "link_url": {
      "type": "string",
      "format": "uri",
      "description": "Shareable deep-link that opens the plans screen with this plan's detail overlay. Give this to the user."
    },
    "plan_uuid": {
      "type": "string",
      "description": "UUIDv4 — the external-facing identifier. Use this for all subsequent calls."
    },
    "created_at": {
      "type": "integer"
    },
    "created_by": {
      "type": "integer"
    },
    "project_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "updated_at": {
      "type": "integer"
    },
    "visibility": {
      "enum": [
        "private",
        "team"
      ],
      "type": "string",
      "description": "private = creator-only; team = visible to all active teammates."
    },
    "assigned_to": {
      "type": "integer"
    },
    "category_id": {
      "type": [
        "integer",
        "null"
      ]
    },
    "description": {
      "type": [
        "string",
        "null"
      ]
    },
    "blueprint_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "completed_at": {
      "type": [
        "integer",
        "null"
      ]
    },
    "dismissed_at": {
      "type": [
        "integer",
        "null"
      ]
    },
    "source_metadata": {
      "type": [
        "object",
        "null"
      ]
    },
    "context_collections": {
      "type": "array"
    },
    "produced_content_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "reference_documents": {
      "type": "array"
    },
    "targeting_dimensions": {
      "type": "array"
    }
  },
  "description": "Full plan object."
}

Instructions

Creates a new content plan in the authenticated user's active team.

Starting stage by source:

cora_requested, playbook -> starts at Accepted
user_added, cora_proactive, workflow -> starts at Suggested

The default source is cora_requested when omitted. source and source_metadata are immutable after creation.

Optional pre-attachments: You can pre-attach reference_document_ids (content UUIDs), context_collection_ids (integer IDs), and targeting_dimension_ids (integer dimension option IDs) at creation time.

Blueprint prompt: Use the prompt field to pre-populate the content creation form when this plan is acted on.

Client-supplied UUID: Pass plan_uuid to supply your own UUIDv4 for optimistic creates; the server generates one if omitted.

Use list_content_categories to get category_id values, list_context_collections for context_collection_ids, list_targeting_dimensions for targeting_dimension_ids, and list_blueprints for blueprint_id.

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.