Create an AI project
POST/ai/projects
Creates a new AI project, or pins or unpins an existing one.
To create a project, omit action. Only ProjectName is required. Category names are cleaned up automatically (extra spaces removed, then capitalized), so finance, FINANCE, and " finance " all become Finance. Do not send Default as a category — that value is assigned automatically when you omit Category. If you omit assistant settings, the first model enabled for chats and the default chat guard rail are used.
If you include Knowledgebases or Agents, linking continues in the background. A 200 means the project was accepted, not that linking has finished — poll GET /ai/projects/{project_id} until ProjectStatus is configured. Projects created without those links start as created.
Project names are not unique. Each successful create returns a new ProjectId, so retrying a successful call creates another project.
To pin or unpin, set action to pin or unpin and send ProjectId in the body. You need at least read-only access, and you can pin up to 10 projects. Repeating either action is safe; Message tells you if nothing changed.
Request
Responses
- 200
- 400
- 500
The project was created, or it was pinned or unpinned. Create returns 200, not 201. ProjectId is included only when a project is created. If you sent Knowledgebases or Agents, Message notes that those components are still being configured.
Response Headers
The request was invalid or you do not have permission. The body is {"Message": " -
Response Headers
An unexpected server error. The body is typically {"Message": "GE-1008 - Could not complete the request. Please try again."}. If the project could not be saved, the error may be DB-1002 and no project is created.