create_ai_project¶

ArtificialIntelligenceApi.create_ai_project(role_id, create_project_request_body, content_type=None, action=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Create an AI project

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.

Parameters:

role_id (str) – Amorphic role used to authorize this request. (required)
create_project_request_body (CreateProjectRequestBody) – (required)
content_type (str)
action (str) – Omit this parameter to create a project. Set to pin or unpin to add or remove the project in the request body from your pinned list. Any other value is treated as create.
_request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.
_request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.
_content_type (str, Optional) – force content-type for the request.
_headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.
_host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

CreateProjectResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: POST /ai/projects

Request¶

Create a project and attach a knowledge base

{
  "ProjectName": "Contracts Assistant",
  "Description": "Answers questions over the contract archive",
  "Keywords": [
    "contracts",
    "legal"
  ],
  "Category": "Legal",
  "EnforceResourceACLs": true,
  "SmartChunking": true,
  "ChatbotName": "Contracts Copilot",
  "Instructions": "Answer only from the linked contracts. Cite the contract name for every claim.",
  "Greeting": "Hi, ask me anything about our contracts.",
  "ChatSuggestions": [
    "Which contracts renew this quarter?",
    "Summarise the Acme MSA termination clause."
  ],
  "Model": "anthropic.claude-sonnet-4-20250514-v1:0",
  "GuardRail": "gr-8f21c47d",
  "Knowledgebases": [
    "2a7d4c19-5e83-4b02-9f61-c3d8a05b7e42"
  ],
  "Agents": [
    "9b3e1f60-7a24-4c85-8d19-2f6b0c4a5e37"
  ]
}

Create a project with only a name

{
  "ProjectName": "Contracts Assistant"
}

Pin a project

{
  "ProjectId": "7c9e6f3a-2b41-4d8e-9a15-6f0c2d5b8e41"
}

Success (HTTP 200)¶

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.

Project created without knowledge bases or agents

{
  "Message": "Project created successfully",
  "ProjectId": "7c9e6f3a-2b41-4d8e-9a15-6f0c2d5b8e41"
}

Project created; linking knowledge bases or agents in the background

{
  "Message": "Project created successfully. Project components are being configured and will be available soon.",
  "ProjectId": "7c9e6f3a-2b41-4d8e-9a15-6f0c2d5b8e41"
}

Project pinned

{
  "Message": "Project pinned successfully"
}

Project was already pinned

{
  "Message": "Project already pinned for user"
}

Project unpinned

{
  "Message": "Project unpinned successfully"
}

Project was not pinned

{
  "Message": "Project not pinned for user"
}

Errors¶

Documented error codes: IPV-1008, IPV-1013, IPV-1068, IPV-1041, IPV-1045, IPV-1002, AUTH-1012, IPV-1076, GE-1008, DB-1002.

HTTP 400

The request was invalid or you do not have permission. The body is {“Message”: “<CODE> - <text>”}. When creating a project, common cases include a missing ProjectName or too many knowledge bases or agents (IPV-1008), Category set to the reserved value Default (IPV-1013), Instructions longer than 15000 characters (IPV-1068), or a model that is not enabled for chats (IPV-1041). When pinning or unpinning, common cases include a missing ProjectId (IPV-1045), a project that does not exist (IPV-1002), no read-only access (AUTH-1012), or more than 10 pinned projects (IPV-1076). Missing permission and not-found cases return 400, not 403 or 404. Invalid JSON returns {“Message”: “Invalid input - <parser error>”} with no error code.

missingProjectName

{
  "Message": "IPV-1008 - Invalid request body, missing key(s) - ProjectName"
}

reservedCategory

{
  "Message": "IPV-1013 - 'Default' is a reserved category and cannot be set explicitly."
}

modelNotEnabled

{
  "Message": "IPV-1041 - Model anthropic.claude-sonnet-4-20250514-v1:0 not available for chat. Please contact your administrator to configure the model for chat use."
}

tooManyPins

{
  "Message": "IPV-1076 - The length of parameter 'pinned projects' exceeds the max limit(10)"
}

HTTP 500

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.

Request / response example

{
  "Message": "GE-1008 - Could not complete the request. Please try again."
}