Vigile
SearchContents

DocumentationOperations

create_project

Create a project, which groups tasks. A prefix of 2 to 8 letters becomes the project's ID and is put in front of the IDs of tasks created in it, as in ABC-042. The prefix cannot be changed later, and no other project can ever have it, also after this one is deleted. Without a prefix the project gets a number as its ID. A new project starts as open.

The operation's own description: what an agent reads to decide whether and how to call it.
It
Changes the plan, as one step that is stored whole or not at all.
Who may call it
Every user.
Version
Takes no version: it is carried out on the plan as it is at that moment. What it creates starts at version 1.
Answers with
The project in short. Its fields: kind, id, title, status, version, progress, has_problems, and sometimes problems, deleted_at. Not in it: description, links, timeline, created_at, created_by, updated_at and unchanged_since. get has those.
MCP tool
create_project
HTTP
POST /api/create-project
Command
vigile create-project

Input

FieldTakesWhat it is
titlestring
1 to 500 characters
required
descriptionstring
at most 4000 characters
optionalWhat the project is for.
prefixstringoptional2 to 8 letters, unique in the tenant, for example ABC.

A field that is not listed here is refused, as invalid_input. On the command line each field is an option, with hyphens for underscores: --title.

Example

The same call three ways, as agent1. It was made on the demo plan the pictures of this site show. Over HTTP and MCP, a call without a key acts as agent1 on a new instance.

Command line

vigile create-project \
  --title "Customer support" \
  --prefix HELP \
  --description "Answer every customer within a day." \
  --as agent1

HTTP

curl -s http://127.0.0.1:8700/api/create-project \
  -H 'content-type: application/json' \
  -d '{"title":"Customer support","prefix":"HELP","description":"Answer every customer within a day."}'

MCP tool call

{
  "name": "create_project",
  "arguments": {
    "title": "Customer support",
    "prefix": "HELP",
    "description": "Answer every customer within a day."
  }
}

The answer

{
  "kind": "project",
  "id": "HELP",
  "title": "Customer support",
  "status": "open",
  "version": 1,
  "progress": { "finished": 0, "total": 0 },
  "has_problems": false
}

This is what a service answered when this page was built. Over HTTP it is the body of the response, over MCP the text of the tool result, and the command line prints it in words unless given --json.

A call that is refused

vigile create-project --title "Web shop, second try" --prefix WEB --as agent1
{
  "error": {
    "code": "rule_violation",
    "message": "The prefix WEB is already used by a project.",
    "rule": "prefix_taken",
    "actions": ["Choose a different prefix."]
  }
}

What it answers

The new project in short: its id, which is the prefix, or a number when no prefix was given, its title, its status (open), its version (1), its progress and whether it has_problems.

Rules

  • A prefix has 2 to 8 letters and nothing else. It is stored in capitals, and it is the project's ID: it cannot be changed later.
  • A prefix is given once. It cannot be one another project has, also a deleted one, or one that a project deleted for good had. The words that start the IDs of other kinds of item cannot be prefixes either: see IDs.
  • Without a prefix the project gets a number as its ID. A task created directly in it gets a bare number; a task also created under a parent whose ID has a prefix uses the parent's prefix instead.
  • The description is optional for a project.

Errors

  • invalid_input: no title, a title of more than one line, a prefix that is not 2 to 8 letters or is a reserved word.
  • rule_violation with the rule prefix_taken: the prefix is in use, or was used.

See also

create_task with project puts a task into it. set_project_status changes its status.