update_ai_project_details¶

ArtificialIntelligenceApi.update_ai_project_details(project_id, role_id, content_type=None, action=None, update_project_request_body=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Update an AI project

Updates an AI project’s metadata and assistant settings, or returns a short-lived URL for uploading the assistant avatar. You need at least editor access. To update the project, omit action and send a JSON body. Only the fields you include are changed; omitted fields keep their current values. Category names are cleaned up the same way as on create, and Default cannot be set explicitly. Changing any assistant field (ChatbotName, Instructions, Greeting, ChatSuggestions, Model, or GuardRail) re-checks the whole assistant configuration, including the currently stored model. Sending Knowledgebases or Agents replaces that entire list (use [] to clear it). Linking continues in the background: ProjectStatus becomes updating, and a 200 means the change was accepted, not that linking has finished. Poll GET /ai/projects/{project_id} until the status is no longer updating. New projects can have up to 5 knowledge bases. A project that already has more may keep or reduce them, with a warning in Message, but cannot add more. To get an avatar upload URL, set action to generate_avatar_url. The request body is ignored. The URL overwrites any existing avatar. Repeating the same update is safe; repeating the avatar call issues a new URL.

Parameters:

project_id (str) – ID of the project to update. If the project does not exist, the API returns 400 (not 404). (required)
role_id (str) – Amorphic role used to authorize this request. (required)
content_type (str)
action (str) – Omit this parameter to update the project. Set to generate_avatar_url to receive an avatar upload URL instead; the request body is then ignored. Any other value is treated as update.
update_project_request_body (UpdateProjectRequestBody) – Required when updating the project. Ignored when requesting an avatar upload URL. All fields are optional; only the fields you send are updated.
_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:

UpdateProjectOrAvatarResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: PUT /ai/projects/{project_id}

Request¶

Required when updating the project. Ignored when requesting an avatar upload URL. All fields are optional; only the fields you send are updated.

Rename and adjust the assistant

{
  "ProjectName": "Contracts Assistant",
  "Description": "Answers questions over the contract archive",
  "Category": "Legal",
  "Greeting": "Hi, ask me anything about our contracts.",
  "Instructions": "Answer only from the linked contracts. Cite the contract name for every claim.",
  "Model": "anthropic.claude-sonnet-4-20250514-v1:0"
}

Replace the linked knowledge bases

{
  "Knowledgebases": [
    "2a7d4c19-5e83-4b02-9f61-c3d8a05b7e42"
  ]
}

Unlink all agents from the project

{
  "Agents": []
}

Success (HTTP 200)¶

The project was updated, or an avatar upload URL was returned. Update responses include Message; avatar responses include PresignedURL — never both. If you sent Knowledgebases or Agents, Message notes that those components are still being configured. Projects with more than 5 knowledge bases include an extra warning.

Updated project metadata only

{
  "Message": "Project metadata updated successfully"
}

Updated; linking knowledge bases or agents in the background

{
  "Message": "Project metadata updated successfully. Project components are being configured and will be available soon."
}

Updated, with a warning that the project has more than 5 knowledge bases

{
  "Message": "Project metadata updated successfully. Project components are being configured and will be available soon. This project has 8 knowledge bases, which exceeds the recommended limit for new projects of 5. Please remove the extra knowledge bases to avoid hitting size limitations."
}

Avatar upload URL

{
  "PresignedURL": "https://example-ml-bucket.s3.us-east-1.amazonaws.com/projects/7c9e6f3a-2b41-4d8e-9a15-6f0c2d5b8e41/avatar.png?X-Amz-Signature=REDACTED"
}

Errors¶

Documented error codes: AUTH-1001, AUTH-1030, AUTH-1012, IPV-1002, IPV-1013, IPV-1068, IPV-1041, IPV-1008, GE-1008.

HTTP 400

The request was invalid or you do not have permission. The body is {“Message”: “<CODE> - <text>”}. Common cases include a missing role_id (AUTH-1001), missing ai.manage permission (AUTH-1030), not being an editor (AUTH-1012), a project that does not exist (IPV-1002, returned as 400 rather than 404), Category set to Default or SmartChunking not a boolean (IPV-1013), Instructions longer than 15000 characters (IPV-1068), a model that is not enabled for chats (IPV-1041), or too many knowledge bases or agents (IPV-1008). Invalid JSON returns {“Message”: “Invalid input - <parser error>”} with no error code.

projectNotFound

{
  "Message": "IPV-1002 - Invalid ProjectId - 7c9e6f3a-2b41-4d8e-9a15-6f0c2d5b8e41, resource not found."
}

notEditor

{
  "Message": "AUTH-1012 - User: jsmith requires at least editor access on the resource to perform this action."
}

smartChunkingNotBoolean

{
  "Message": "IPV-1013 - Invalid parameter - SmartChunking, this field value must be a boolean value."
}

tooManyKnowledgebases

{
  "Message": "IPV-1008 - Number of knowledge bases cannot exceed 5. Found 7."
}

HTTP 500

An unexpected server error. The body is typically {“Message”: “GE-1008 - Could not complete the request. Please try again.”}. Updating a project without a request body also returns 500.

Request / response example

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