[EPD-198] Document restoreFromStateId in kickoff API reference + migration guide operational notes

[joaomdmoura]

• Add restoreFromStateId (optional string, uuid format) to the POST /kickoff request schema in docs/edge/enterprise-api.en.yaml (and the in-sync enterprise-api.base.yaml): documents fork semantics (hydrates from the referenced state, the new run gets a fresh state id), the silent fresh-session fallback when the id is unknown, and links to the migration guide
• Add a flow_state_restore request example and document the 422 variant where a non-UUID inputs.id is rejected ("'inputs.id' must be a valid UUID when provided; got 'test 1'.") alongside the existing missing_inputs case
• Add an "Operational notes" section to docs/edge/en/guides/flows/inputs-id-deprecation.mdx covering: the API does not yet return the minted state id (chain turns today by pinning a client-generated UUID via inputs.id alongside restoreFromStateId; gap is tracked), unknown restoreFromStateId silently starts a fresh session with no failure signal, and AMP's UUID format requirement for inputs.id
• Edge-only per AGENTS.md: frozen docs/v*/ snapshots and non-English locales untouched
• Linear: https://linear.app/crewai/issue/EPD-198

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only changes to Edge guides and OpenAPI YAML; no runtime or API implementation changes.

Overview
Documents restoreFromStateId on POST /kickoff in the Edge OpenAPI specs (enterprise-api.en.yaml / enterprise-api.base.yaml): optional UUID to hydrate from a prior @persist flow with fork semantics, silent fresh session when the id is unknown, plus a flow_state_restore example. 422 is expanded to cover invalid inputs.id (non-UUID) with concrete response examples alongside missing inputs.

The inputs.id deprecation guide gains an Operational notes section for AMP REST chaining: the API still does not return the new run’s minted state id (interim pattern of client UUID via inputs.id + restoreFromStateId), unknown restore ids fail open with no signal, and AMP requires UUID-shaped inputs.id.

^{Reviewed by Cursor Bugbot for commit f90f735. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear]

EPD-198

[coderabbitai]

📝 Walkthrough

Walkthrough

The AMP /kickoff contract now supports restoreFromStateId, includes restoration examples, and documents structured 422 validation errors. An operational guide describes state restoration behavior, UUID requirements, and multi-turn chaining considerations.

Changes

AMP kickoff state restoration

Layer / File(s)	Summary
Kickoff restoration contract and validation docs/edge/enterprise-api.*.yaml	Adds the optional restoreFromStateId UUID field, restoration request examples, and detailed validation examples for missing inputs and invalid inputs.id values.
Operational restoration notes docs/edge/en/guides/flows/inputs-id-deprecation.mdx	Documents response behavior, client-side UUID handling, unknown state IDs, and UUID validation for inputs.id.

Suggested reviewers: vinibrsl

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly matches the main change: documenting restoreFromStateId in the kickoff API reference and migration guide.
Description check	✅ Passed	The description accurately summarizes the documented API schema updates, examples, validation cases, and migration guide notes.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch joao/epd-198-docs-restorefromstateid-missing-from-post-kickoff-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
crewai	🟢 Ready	View Preview	Jul 14, 2026, 5:14 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/edge/en/guides/flows/inputs-id-deprecation.mdx`:
- Around line 156-159: Replace the non-UUID placeholder values in the request
example with valid UUID-formatted placeholders for both inputs.id and
restoreFromStateId, while preserving the example’s meaning and surrounding flow.

In `@docs/edge/enterprise-api.base.yaml`:
- Line 152: Replace the invalid UUID examples with a valid hexadecimal UUID
placeholder at docs/edge/enterprise-api.base.yaml lines 152-152 and 197-197, and
docs/edge/enterprise-api.en.yaml lines 152-152 and 197-197; update both the
example and restoreFromStateId values while leaving unrelated kickoff_id
occurrences unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3976ae72-27a5-4a7d-87c7-1c203330ce29

📥 Commits

Reviewing files that changed from the base of the PR and between 9d72e26 and 1f025fc.

📒 Files selected for processing (3)

• docs/edge/en/guides/flows/inputs-id-deprecation.mdx
• docs/edge/enterprise-api.base.yaml
• docs/edge/enterprise-api.en.yaml

[joaomdmoura]

Addressed CodeRabbit feedback: the examples this PR added now use valid UUIDs (schema example, flow_state_restore request example, and the migration-guide curl placeholders). Note: the pre-existing example UUID pattern abcd1234-5678-90ef-ghij-klmnopqrstuv used elsewhere in enterprise-api yaml contains non-hex characters and is invalid against format: uuid — left untouched here as a repo-wide cleanup for a separate pass.