Content

create_content

Create a content document from an AI prompt, your own supplied text, or a blueprint template. It automatically pulls in all relevant brand and reference context, so there is no need to fetch context first. When generating from `instructions`, you can also pass `reference_content_ids` to fold specific existing documents into the prompt as reference material.

Parameters

Name	Type	Required	Default	Description
`content`	`string`	No	—	Pre-written text to save directly as a document (no AI generation). Mutually exclusive with `instructions` and cannot be combined with `blueprint_uuid`. Prefer markdown-formatted content. Use a markdown conversion tool first if you have a url or html.
`instructions`	`string`	No	—	AI prompt describing what to create. Mutually exclusive with `content`. Required if `content` is omitted.
`blueprint_uuid`	`string (uuid)`	No	—	UUID of a blueprint to generate from (get from list_blueprints). When set, this becomes an ASYNC call — poll get_generation_status with the returned generation_id. Only valid with `instructions`.
`category_id`	`integer`	No	—	Optional content category id from list_content_categories. Organizational only — does not change generation behavior.
`collection_ids`	`array of integers`	No	—	Optional context collection IDs (from list_context_collections) to include during generation, on top of the always-on Brand Foundation + Reference Library + Project Context.
`dimension_option_ids`	`array of integers`	No	—	Optional targeting dimension OPTION IDs (from list_targeting_dimensions — drill into each dimension's options) to shape the generation for a specific audience (e.g. persona, industry, buying stage).
`project_id`	`string (uuid)`	No	—	Optional project UUID (from list_projects) to associate the new content with. When set, the project's Project Context (brief + project context items) is automatically included in generation.
`use_extended_thinking`	`boolean`	No	false	Set true for complex content that benefits from deeper reasoning. Only applies to the freeform sync path (`instructions` without `blueprint_uuid`).
`plan_id`	`string`	No	—	Optional plan UUID (from create_plan / list_plans / get_plan — use plan_uuid, not the integer id). Associates the new content with the plan and triggers an automatic stage transition to In_Process. Linkage applies only when used WITH blueprint_uuid (the async blueprint-generation path); sync paths accept the field without error but do not auto-link. Invalid plan_id is logged but does NOT fail content creation. Do NOT pass if the plan is in Complete stage — call update_plan target_stage='Accepted' first.
`reference_content_ids`	`array of string`	No	—	Optional content UUIDs (from list_content, or list_content with `search`) whose full text is folded into the generation prompt as reference material. The canonical way to have Marcora write with reference to existing documents — no need to paste their text into `instructions`. Valid only on the generation paths (`instructions`, with or without `blueprint_uuid`); rejected with the verbatim `content` path. An unknown or inaccessible id fails the whole call (never silently skipped).

Input Schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Pre-written text to save directly as a document (no AI generation). Mutually exclusive with `instructions` and cannot be combined with `blueprint_uuid`. Prefer markdown-formatted content. Use a markdown conversion tool first if you have a url or html."
    },
    "plan_id": {
      "type": "string",
      "format": "uuid",
      "description": "Optional plan UUID (from create_plan / list_plans / get_plan — use plan_uuid, not the integer id). Associates the new content with the plan and triggers an automatic stage transition to In_Process. Linkage applies only when used WITH blueprint_uuid (the async blueprint-generation path); sync paths accept the field without error but do not auto-link. Invalid plan_id is logged but does NOT fail content creation. Do NOT pass if the plan is in Complete stage — call update_plan target_stage='Accepted' first."
    },
    "project_id": {
      "type": "string",
      "format": "uuid",
      "description": "Optional project UUID (from list_projects) to associate the new content with. When set, the project's Project Context (brief + project context items) is automatically included in generation."
    },
    "category_id": {
      "type": "integer",
      "description": "Optional content category id from list_content_categories. Organizational only — does not change generation behavior."
    },
    "instructions": {
      "type": "string",
      "description": "AI prompt describing what to create. Mutually exclusive with `content`. Required if `content` is omitted."
    },
    "blueprint_uuid": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of a blueprint to generate from (get from list_blueprints). When set, this becomes an ASYNC call — poll get_generation_status with the returned generation_id. Only valid with `instructions`."
    },
    "collection_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Optional context collection IDs (from list_context_collections) to include during generation, on top of the always-on Brand Foundation + Reference Library + Project Context."
    },
    "dimension_option_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Optional targeting dimension OPTION IDs (from list_targeting_dimensions — drill into each dimension's options) to shape the generation for a specific audience (e.g. persona, industry, buying stage)."
    },
    "reference_content_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Optional content UUIDs (from list_content, or list_content with `search`) whose full text is folded into the generation prompt as reference material. The canonical way to have Marcora write with reference to existing documents — no need to paste their text into `instructions`. Valid only on the generation paths (`instructions`, with or without `blueprint_uuid`); rejected with the verbatim `content` path. An unknown or inaccessible id fails the whole call (never silently skipped)."
    },
    "use_extended_thinking": {
      "type": "boolean",
      "description": "Set true for complex content that benefits from deeper reasoning. Only applies to the freeform sync path (`instructions` without `blueprint_uuid`)."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "Content record ID (only present without blueprint)."
    },
    "title": {
      "type": "string",
      "description": "Document title (only present without blueprint)."
    },
    "content": {
      "type": "string",
      "description": "Document content in markdown (only present without blueprint)."
    },
    "link_url": {
      "type": "string",
      "format": "uri",
      "description": "Direct URL to view/open this content in Marcora (only present without blueprint)."
    },
    "content_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier — use as content_id in get_content and share tools (only present without blueprint)."
    },
    "created_at": {
      "type": "integer",
      "description": "Unix timestamp of creation (only present without blueprint)."
    },
    "generation_id": {
      "type": "string",
      "format": "uuid",
      "description": "ID to track async generation — pass to get_generation_status (only present WITH blueprint)."
    }
  },
  "description": "When content is provided, returns the saved content object. When instructions are provided without blueprint, returns the AI-generated content object. When blueprint_uuid IS provided, returns only generation_id."
}

Instructions

Use this tool to create content. You can supply your own text directly, create content from an AI prompt, or generate from a blueprint.

You must provide either content or instructions (not both).

With content (synchronous):
Saves your supplied text directly as a document — no AI generation. Returns immediately.

With instructions (synchronous):
Creates a freeform document from an AI prompt. SYNCHRONOUS — typically takes 1-3 minutes. Returns the content object directly.

With instructions + blueprint_uuid (asynchronous):
Generates content from a blueprint template. ASYNC — returns a generation_id immediately. You must then poll get_generation_status with the generation_id until the status is "completed". This typically takes 3-5 minutes.

Referencing existing content (reference_content_ids):
Optional array of content UUIDs. Only valid on a GENERATION path (instructions, with or without blueprint_uuid). Marcora resolves each id, pulls that document's full text, and folds it into the generation prompt as reference material — used to inform the new piece, not reproduced verbatim unless you ask. This is the first-class way to generate NEW content that draws on EXISTING content (e.g. "write a follow-up email based on this case study", "draft a post drawing on these three docs"). Get the UUIDs from list_content (content_id) or get_content; list_content's search helps you find the right ones by meaning. Do NOT combine with the verbatim content path — passing both fails loud. A bad or inaccessible id also fails loud, naming the id (never silently skipped).

Linking to a Plan:
Pass plan_id (the plan_uuid from create_plan, list_plans, or get_plan) to associate the new content with a plan. When used with blueprint_uuid, this also automatically transitions the plan to In_Process stage. Sync paths accept the field without error but do not auto-link. If the plan is already in Complete stage, call update_plan with target_stage=Accepted first.

Workflow:

Provide content (your own text) OR instructions (AI prompt) — not both.
Optionally provide blueprint_uuid from list_blueprints to generate from a template (only with instructions).
Optionally provide reference_content_ids (UUIDs from list_content / get_content) to fold existing documents into the prompt as reference material — generation paths only, not valid with content.
Optionally provide plan_id from list_plans or create_plan to link content to a plan.
Optionally get category_id from list_content_categories.
Optionally get dimension_option_ids from list_targeting_dimensions.
Optionally get collection_ids from list_context_collections.
Set use_extended_thinking=true for complex content (only applies with instructions without blueprint).

Examples

Save direct content (sync)

Supply your own text directly as a document — no AI generation. SYNCHRONOUS — returns immediately.

Input

{
  "content": "# Product Update Q2 2026\n\nWe shipped three major features this quarter...\n\n## SSO Integration\n\nEnterprise customers can now sign in with their existing identity provider.",
  "category_id": 5,
  "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Output

{
  "id": 1235,
  "content_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Product Update Q2 2026",
  "content": "# Product Update Q2 2026\n\nWe shipped three major features this quarter...\n\n## SSO Integration\n\nEnterprise customers can now sign in with their existing identity provider.",
  "created_at": 1712678400,
  "link_url": "https://app.marcora.ai/canvas/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Generate content from a blueprint (async)

Use a blueprint template with context collections and targeting dimensions. This is ASYNCHRONOUS — returns a generation_id immediately. Poll get_generation_status with the generation_id until status is completed.

Input

{
  "instructions": "Write a blog post about our new enterprise SSO feature. Focus on security benefits and ease of setup.",
  "blueprint_uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "category_id": 5,
  "collection_ids": [3, 7],
  "dimension_option_ids": [12, 45],
  "project_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Output

{
  "generation_id": "7c9e6a2b-1f4d-4a8e-b3c5-9d2e1f6a4b8c"
}

Quick content from AI prompt (sync)

Generate content from instructions without a blueprint. This is SYNCHRONOUS — returns the full content object directly (typically 1-3 minutes). No need to poll get_generation_status.

Input

{
  "instructions": "Write a short LinkedIn post announcing our Series B funding. Keep it under 200 words, celebratory but professional."
}

Output

{
  "id": 1234,
  "content_id": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
  "title": "Series B Funding Announcement",
  "content": "# We just closed our Series B!\n\nThrilled to announce...",
  "created_at": 1712678400,
  "link_url": "https://app.marcora.ai/canvas/e5f6a7b8-c9d0-1234-ef01-234567890abc"
}