Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
DESTRUCTIVE

create_project

Creates a project on the team's registry from a name and a paragraph, with the key suggested when none is given, so Heimdall can open a project in conversation.

Create a project: name is required and unique within the team; key, two to six upper-case letters and digits starting with a letter, is the prefix of every reference inside the project (SCL-12) and is suggested from the name when left out; client_id names one of the team's clients (omit it for an internal project); description holds the brief as HTML; tagline, status (discovery by default), methodology (scrum by default), visibility (team by default), the four lead ids, starts_on, target_launch_on, launched_on and budget_hours fill in the rest. The project is written through the same action the registry page and the intake wizard run, and project.created goes out.

This is the door the conversational intake opens: find or create the client, create the project with the brief as its description, then write the record under it with the component, environment, stakeholder, persona, epic, story, requirement, rule and glossary tools, and convene the council on the project when the scaffold is in. The answer carries the key chosen, which every later reference uses. A staff token with project:create is needed.

Requires ability

project:create

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same action as

POST/v1/projects

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Fires one event

project.created

Delivered to every endpoint subscribed to it once the change is made.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

name*string

The project's name, 3 to 100 characters, unique within the team.

keystringoptional

Two to six upper-case letters and digits starting with a letter, such as SCL; suggested from the name when left out.

client_idstringoptional

UUID of the client the project is for; omit for an internal project.

taglinestringoptional

One line about the project, up to 160 characters.

descriptionstringoptional

What the project is, as HTML; the brief as the person gave it fits here.

statusstringoptional

The lifecycle status; discovery by default.

discoveryplanningin_developmentin_testinglivemaintenanceon_hold
methodologystringoptional

How the project is run; scrum by default.

scrumkanbanhybridwaterfall
visibilitystringoptional

team when every member sees it, members_only when only its project members do.

teammembers_only
lead_pm_idstringoptional

UUID of the project manager, a member of the team.

lead_ba_idstringoptional

UUID of the lead business analyst.

lead_dev_idstringoptional

UUID of the lead developer.

lead_qa_idstringoptional

UUID of the QA lead.

starts_onstringoptional

The planned start, YYYY-MM-DD.

target_launch_onstringoptional

The target launch, YYYY-MM-DD, on or after the start.

launched_onstringoptional

The day the project went live, YYYY-MM-DD.

budget_hoursintegeroptional

The budgeted effort in whole hours.

What it returns

{  "data": {    "id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "team_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",    "client_id": "9b1f2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",    "key": "SCL",    "name": "Super Clean Laundry",    "tagline": "Laundry orders, tracking, payment and pickups online",    "description": "<p>An informational website with laundry order placement, tracking, payment and appointment scheduling.</p>",    "status": "discovery",    "methodology": "scrum",    "visibility": "team",    "health": "unknown",    "lead_pm_id": null,    "lead_ba_id": null,    "lead_dev_id": null,    "lead_qa_id": null,    "starts_on": null,    "target_launch_on": null,    "launched_on": null,    "budget_hours": null,    "archived_at": null,    "created_at": "2026-10-28T09:15:00+00:00",    "updated_at": "2026-10-28T09:15:00+00:00"  }}

How it fails

VALIDATION_FAILED

name missing or outside 3 to 100 characters, a key that is not two to six upper-case letters and digits starting with a letter, a key or a name the team already had, a client_id that is not the team's, a lead who is not on the team, a launch before the start, or status set to archived.

FORBIDDEN

the token is a client guest's, or the holder's team role does not carry project:create.

TOKEN_MISSING_ABILITY

token lacks project:create.

Related

create_clientthe client first, when it is new.update_projectthe dates, the leads and the client later.create_componentthe first thing under a new project.convene_councilthe council on the scaffold once it is in.Projects APIthe same door over REST.

How is this guide?

Last updated on