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.

Delete a goal created via the API.

Use this when regenerating a goal after a learner retakes a skill assessment: call create_goal with the new suggested_goal_seed, then call delete_goal on the obsolete goal so the learner's dashboard shows the current goal instead of duplicates.

Soft delete by default (status='deleted'); the dashboard already filters these out, but a superadmin can restore them. Set hard_delete=true to permanently remove the row and cascade to steps, plans, and share links.

Scoped to api-created goals in your org -- you cannot delete goals a user created in the webapp UI. Calling twice with the same goal_id is safe (soft delete is idempotent).

Get the current status and progress of a goal.

Returns who claimed it, step completion breakdown, plan generation status, and the embeddable progress report link.

Use this to check if plan generation is complete (planGenerationStatus: "completed") or to monitor a learner's progress.

List all goals in your org created via the API.

Filter by goal status (draft, in_progress, completed), claim status (unclaimed, claimed, expired, revoked), metadata tags, assigned learner email, or inactivity (at-risk detection).

Use this to see all learner goals, check progress across a cohort, find unused claim links, or identify learners who have gone inactive.

For aggregate cohort metrics, use get_analytics instead.

Invalidate a claim link so it can no longer be used.

Does not remove access from a user who already claimed the goal. Use this if a link was sent to the wrong person or needs to be regenerated.

Get pending clarification questions for a goal with agent-suggested answers.

Use this after create_goal with auto_respond=false. Returns the list of clarification questions along with what the agent suggested for each one, including confidence levels and reasoning.

Review the suggestions, then use submit_clarification to accept or override them.

Submit answers to clarification questions and trigger plan generation.

Use after create_goal with auto_respond=false. Provide your own answers for questions you want to override. Set accept_agent_answers=true (default) to keep the agent's suggestions for all questions you did not explicitly answer.

After submission, the plan generates asynchronously. Use get_goal_status to check when planGenerationStatus changes to "completed".

Import a pre-formulated plan with steps and substeps into Unfold.

Skips clarification entirely. Use this when you already have a structured plan (e.g. from Jira, Linear, or your own planning tool).

Optionally enriches steps with AI-generated metadata: dependencies between steps, critical path identification, duration estimates, severity/complexity ratings, and quick-win flags. Set enrich=false to skip AI enrichment (0 credits).

Returns the goal with a claim link and the enriched step list.

Get aggregated analytics for your organization's goals.

Returns cohort KPIs (total, active, completed, blocked), claim metrics (activation rate, time-to-claim), at-risk learners (inactive for N days), an optional step-level completion funnel, and optional resource engagement breakdown.

Use groupBy to break down completion rates by a metadata dimension (e.g. groupBy="track" shows completion rates for frontend, backend, etc).

Use the metadata filter to narrow the scope to a specific cohort or department (e.g. metadata={cohort: "spring-2026"}).

Examples:

• "How is the spring 2026 cohort doing?" -> get_analytics({ metadata: { cohort: "spring-2026" } })

• "Which track has the highest completion rate?" -> get_analytics({ groupBy: "track" })

• "How many students are at risk this week?" -> get_analytics({ inactiveDays: 7 })

• "Show me the step-by-step funnel for the frontend track" -> get_analytics({ metadata: { track: "frontend" }, includeFunnel: true })

Generate a skill-proficiency assessment (MCQs) for a learner.

You provide a skill, target proficiency, number of questions, and the work item the learner is preparing for. Unfold returns the questions with multiple-choice options, a signed assessment_token, and a proficiency band map. The learner answers in your UI; then call score_skill_assessment with the token and answers.

Questions are AI-generated and validated (structural + semantic) before being returned. The assessment_token is HMAC-signed and tamper-proof; it contains the answer key AND per-question facet labels (since v0.7.0) so scoring is stateless and deterministic, and score returns per-facet aggregation without you doing any client-side joins.

CHAINING:

• work_item_context is the strongest grounding signal: questions get anchored to it instead of being generic textbook items. Pass title + description whenever you have them.

• The same work_item_context flows through to score_skill_assessment's suggested_goal_seed, then into create_goal. Keep it consistent across the chain.

TYPED ERRORS (branch on error_code):

• "models_not_configured" / "provider_unauthorized" / "provider_quota_exceeded" / "provider_unavailable" / "provider_request_invalid": LLM provider issues. Some include settings_url and switch_to_unfold_ai CTA.

• "validation_failed": generation produced output the validator rejected after retry budget. Retry with a different request_id, or reduce num_questions.

• "idempotency_conflict": same request_id was used with a different request body; pick a new request_id.

Requires the "assessment:generate" scope on your org API key.

Score a skill assessment using answers and the assessment_token from generate_skill_assessment.

Returns the raw score, percentage, proficiency band, gap vs target, and per-question results. When the learner falls short of the target band, includes a suggested_goal_seed you can pass to create_goal.

PER-FACET AGGREGATION (since v0.7.0): Response also includes per_facet (one entry per sub-skill with total, correct, raw_pct, classification) and shortlists weak_facets + strong_facets. Aggregation is computed server-side from facets embedded in the signed token, so partners do not write join logic. The facet_coverage field tells you whether facet labels are real ("full"), partially synthetic ("partial"), or entirely difficulty-bucket fallbacks ("difficulty_fallback") -- soften "weak in X" UI framing when coverage is not "full".

CHAINING into create_goal: The shape of this response is purpose-built to drop straight into create_goal's 'assessment' field (as a skill_proficiency v1 variant):

• band -> achieved_band

• target_band -> target_band

• raw_pct, gap_bands -> same names

• weak_facets, strong_facets -> same names

• work_item_context comes from your original generate_skill_assessment call Add assessment_type: "skill_proficiency", schema_version: "v1", and assessed_at (ISO 8601 current time) headers.

Scoring is stateless and deterministic: the signed assessment_token contains the answer key. Tampered or expired tokens are rejected. Same request_id returns the same result (idempotent).

TYPED ERRORS (branch on error_code):

• "token_invalid": signature mismatch or malformed token. Regenerate via generate_skill_assessment.

• "assessment_expired": token past TTL. Regenerate.

• "idempotency_conflict": same request_id was used with different answers; pick a new request_id.

Requires the "assessment:score" scope on your org API key.

Get supported parameters for skill assessments.

Returns the schema version, supported languages, min/max question count, proficiency bands, default band thresholds, default difficulty mix, and whether the system is open-domain (accepts any skill) or restricted.

Use this to introspect before calling generate_skill_assessment. No parameters required.

Requires the "assessment:read_capabilities" scope on your org API key.

List available resource categories for goal classification.

Returns the categories you can use in create_goal's category field or as a filter in list_goals. Each category has different resource providers, content safety policies, and plan generation behavior.

For example, "health_adhd" restricts resources to curated clinical sources, excludes medication content, adds disclaimers, and generates shorter substeps with transition rituals. "learning" adds YouTube, GitHub, and Official Docs providers alongside web search.

Use this to build adaptive UIs that show category-specific options to your users.