Deployed Crew API Contract

Every endpoint, field, state and error a client of a deployed crew or flow needs, each with the public page it comes from, and - where a live deployment on CrewAI AMP answered differently on 2026-10-01 - what it actually returned. Re-check the linked pages when something here disagrees with what you see.

Sources:

• API reference (OpenAPI): https://docs.crewai.com/en/api-reference/introduction and its endpoint pages
• Platform guide: https://docs-platform.crewai.com/platform/en/guides/kickoff-crew
• Webhook streaming: https://docs-platform.crewai.com/platform/en/features/webhook-streaming
• Flow state restore: https://docs.crewai.com/en/guides/flows/inputs-id-deprecation

1. Base URL and authentication

2. GET /inputs

Response 200: {"inputs": ["budget", "interests", "duration", "age"]} - the names of the inputs the crew requires. Errors: 401, 404, 500. Source: https://docs.crewai.com/en/api-reference/inputs

Locally, the same names come from the {placeholder} tokens in task description / expected_output and agent role / goal / backstory; Crew.fetch_inputs() returns them as a set.

Flows (live): /inputs returned the fields the state model declares - {"inputs": ["topic", "count", "id", "history"]} for a model that declared id; another flow whose model did not declare id listed only its own fields. None is required; do not send id.

3. POST /kickoff

Source: https://docs.crewai.com/en/api-reference/kickoff

Response 200: {"kickoff_id": "<uuid>"}.

Errors as documented, and as returned live:

Flows: the deprecated way to continue a @persist flow was {"inputs": {"id": "<uuid>", ...}}. The docs say that on AMP reusing an inputs.id resolves to the existing execution record, so status, traces and the executions list of the old run get overwritten or merged. Send restoreFromStateId beside inputs instead; each kickoff then stays its own execution.

Live (@persist flow, no LLM): a run's state.id equals its kickoff_id. restoreFromStateId: <kickoff_id of run 1> gave count=2 under a new state id (= the new kickoff_id); chaining from run 2 gave count=3; an unknown id ran from defaults without error. inputs.id = <run 1 kickoff_id> also restored, but the run wrote its state back under run 1's id.

4. GET /status/{kickoff_id}

Two documented shapes. Live deployments returned the platform guide shape; a client should still accept both.

Observed behaviour (crew and flow):

• States seen: PENDING, STARTED, RUNNING, SUCCESS, FAILED, and NOT FOUND (with a space). PAUSED / REVOKED were not seen.
• An unknown or malformed id returns HTTP 200 with {"state": "NOT FOUND", "status": "Task not found or Invalid kickoff id", ...} - not 404.
• status is a message: "Task is pending", "Task is Running", the exception text on FAILED ("ValueError: ..."), null on SUCCESS.
• result is the final output string; result_json was null for a plain-text result; usage_metrics carried token counts; execution_origin was api; last_executed_task held the last task's name, interpolated description, output, kickoff_id and meta.
• Crew progress: {"unit": "task", "completed": 1, "total": 2, "remaining": 1, "current": "summary_task", ...}. Flow progress: {"unit": "step", "total": null, "remaining": null, ...}.
• A failed run: state: FAILED, result: null, progress: null.

Platform guide shape (https://docs-platform.crewai.com/platform/en/guides/kickoff-crew):

Notes from the same page:

• For a flow, progress.total and progress.remaining are always null. Show completed as a count, not a percentage.
• A queued execution has state PENDING.
• Progress and event data are null for deployments on crewai 1.15.21 or earlier, and when source is application.
• Deployment env vars CREWAI_STATUS_EVENTS, CREWAI_STATUS_MAX_EVENTS, CREWAI_STATUS_EVENT_FLUSH_SECONDS tune the event log.

API reference shape (https://docs.crewai.com/en/api-reference/status):

{"status": "running", "current_task": "research_task", "progress": {"completed_tasks": 1, "total_tasks": 3}}
{"status": "completed", "result": {"output": "...", "tasks": [{"task_id": "...", "output": "...", "agent": "...", "execution_time": 45.2}]}, "execution_time": 108.5}
{"status": "error", "error": "Task execution failed: ...", "execution_time": 23.1}

404: {"error": "Execution not found", "message": "No execution found with ID: ..."}.

Client rules that cover both:

5. POST /resume

Source: https://docs.crewai.com/en/api-reference/resume

For crews where a task has human_input=True: the execution pauses after that task and waits for feedback.

Response 200: {"status": "resumed" | "retrying" | "completed", "message": "..."}. 400 when the execution is not waiting for human input; 404 for an unknown execution or task id.

The HITL Workflows guide adds a kickoff field, humanInputWebhookUrl, called when the task waits for review.

Before building on crew human_input=True over the API, verify the whole cycle on your own deployment: pass humanInputWebhookUrl (it is the only signal that a run is waiting; its body carries execution_id and a UUID task_id), handle NOT FOUND as well as PAUSED from /status while waiting, check which field casing (executionId/taskId or snake_case) your deployment accepts, and confirm the resumed run reaches SUCCESS.

For flows, human review uses @human_feedback; see https://docs.crewai.com/en/learn/human-feedback-in-flows.

6. Webhook streaming

Source: https://docs-platform.crewai.com/platform/en/features/webhook-streaming

{
  "inputs": {"topic": "AI agents"},
  "webhooks": {
    "events": ["crew_kickoff_started", "task_completed", "crew_kickoff_completed", "crew_kickoff_failed"],
    "url": "https://your-server.example.com/crewai-events",
    "realtime": false,
    "authentication": {"strategy": "bearer", "token": "<your-webhook-secret>"}
  }
}

• Each delivery is {"events": [{"id", "execution_id", "timestamp", "type", "data"}]}; data depends on the event type. Live: data.emission_sequence is present on every event.
• Delivery order is not guaranteed; order by timestamp. Live with realtime: true, a task_started arrived before the previous task_completed.
• realtime: true sends each event immediately, at some cost to run performance; otherwise events are batched. Live: realtime: false sent 4 events in one POST; realtime: true sent one POST per event.
• Live: the streaming POST carried Authorization: Bearer <your-webhook-secret>. The taskWebhookUrl / crewWebhookUrl / humanInputWebhookUrl POSTs carried no Authorization header - confirm them by kickoff_id with GET /status.
• Event names match crewai's event bus: flow (flow_started, flow_finished, method_execution_*), crew (crew_kickoff_started / _completed / _failed), task (task_started, task_completed, task_failed), agent, tool, LLM, memory, knowledge and reasoning events. See the page for the full list.
• Your endpoint should reject requests without the bearer secret you configured, and be idempotent on event id.

7. Error codes summary