create_goal
Create a goal with an AI-generated plan and generate a one-time claim link for users to join your org and start executing.
Instructions
Create a goal in your Unfold org with an AI-generated plan.
Returns a one-time claim link to send to the user. When they click it, they auto-join your org, get assigned the goal, and land directly on it with a fully AI-generated plan ready to execute.
The plan generates asynchronously (15-30s). The claim link works immediately. Use get_goal_status to check when planGenerationStatus changes to "completed".
With auto_respond=true (default), the agent answers all clarification questions automatically using the provided context. Set auto_respond=false to get questions back with agent suggestions for client review -- then use submit_clarification to provide your answers.
CHAINING:
If you have an assessment scored via score_skill_assessment, drop its response (band, target_band, per_facet, weak_facets, work_item_context) into the 'assessment' field. The planner will prioritise weak facets, skip strong ones, and anchor steps in the work item.
Each goal is for one user. Call this once per learner/user.
TYPED ERRORS (branch on error_code):
"models_not_configured": tenant's BYO provider has no role configured. Response includes settings_url for the user to fix it.
"provider_unauthorized" / "provider_quota_exceeded": BYO provider key rejected. Response may include switch_to_unfold_ai CTA.
"assessment_type_not_supported": you sent an assessment whose prompt builder is not yet wired (e.g. clinical_intake before partner integration). Response.details.supported lists what IS wired.
WARNINGS (non-fatal, surfaced in response.warnings):
"category_assessment_type_mismatch": category and assessment_type disagree (e.g. learning + clinical_intake). The plan was generated using assessment_type. Set category to align if you want category-aware resource routing.
"duplicate_assessment_input": you sent both the structured 'assessment' field and the legacy unfold_assessment envelope inside additional_context. Structured wins.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Goal title, e.g. 'AI Fundamentals Learning Path' | |
| context | No | Structured context the planner honours directly (not paraphrased via clarification). Higher-priority than free-form description. | |
| category | No | Goal category for resource routing. Auto-detected from title if omitted. 'learning' = technical skills, courses, upskilling. 'health_adhd' = ADHD management, executive function, habit building. 'general' = everything else. If you also pass `assessment`, prefer the matching category (learning <-> skill_proficiency, health_adhd <-> clinical_intake) to avoid the category_assessment_type_mismatch warning. | |
| metadata | No | Custom key-value tags for filtering and analytics (e.g. {cohort: 'spring-2026', track: 'frontend', department: 'engineering'}). Used in get_analytics to group and filter results. | |
| priority | No | medium | |
| assessment | No | Structured assessment input. Discriminated by assessment_type: - skill_proficiency v1: drop the score_skill_assessment response directly here. The planner uses band/target_band/weak_facets/strong_facets/work_item_context for a targeted plan. - clinical_intake v1: ADHD/coaching/clinical context. Wire shape is locked; the prompt builder is not yet wired (you will get assessment_type_not_supported until a real partner drives it). - general v1: catch-all for assessment data that does not fit either typed shape. Treated as soft hints; `constraints` are the only hard limits. | |
| request_id | No | Idempotency key. Within a 5-minute window, two calls with the same request_id return the SAME goal and claim link instead of creating a new one. MUST be unique per logical operation (per learner / per enrollment). Two different learners with identical title/description/assessment MUST use different keys -- if you reuse a key across learners, the second learner receives a claim link the first learner already claimed. Recommended construction: derive from your own enrollment_id, or `${course_id}:${learner_id}`. Omit to get a fresh goal on every call (the default). On a replay, the response's `idempotentReplay` is true and `claimStatus` reflects current DB truth so you can detect a link that was already consumed. | |
| description | No | Goal description with context. More detail produces a better AI plan. | |
| auto_respond | No | true = fully autonomous (agent answers all questions). false = returns questions with suggestions for review. | |
| goal_context | No | professional | |
| progress_share | No | Generate an embeddable progress report link | |
| resource_world | No | Per-goal resource config. Overrides org defaults for this goal's resource discovery. | |
| claim_expires_in_days | No | How many days the claim link stays valid | |
| clarification_answers | No | Pre-set answers by question ID. Agent skips these questions. |