Artificial Intelligence

APIs related to AI components such as models, agents, knowldegebases, guardrails, chats, notes etc.

📄️ Get AI configurations

Returns enablement status for every supported AI component, plus assigned models, default model and guard rails for enabled model-configurable components.

Enables or disables AI services and updates per-component model and guard rail configurations. Partial update - only the listed components are acted on. Service enablement is applied before model and guard rail changes, so a late failure leaves the enablement changes in place.

📄️ Migrate RAG engine

Initiates RAG engine migration for knowledge bases (for example between OpenSearch and Aurora RDS). Requires action=repair and resource=knowledgebases. No request body is used.

📄️ List AI models

Returns available AI models. Three list modes:

📄️ Sync AI models from Bedrock

Re-reads the Bedrock foundation model catalog and reconciles it into the Amorphic AI models table: new models are added, models Bedrock no longer lists are marked deprecated, and inference profile metadata is refreshed.

📄️ Get model details or invocation status

Two distinct reads on the same path, selected by the action query parameter. The two modes return different fields; both are described by AIModelDetails.

📄️ Update model status or parameters

Five mutations on a single model, selected by the required action query parameter. All of them are synchronous - a 200 means the change is persisted.

📄️ Invoke model

Starts an asynchronous text generation against an enabled AI model. A 200 means accepted, not complete: the call records an invocation with status IN_PROGRESS, and returns immediately with an InvocationId.

📄️ List chats

Returns a paginated list of playground chats the user can access (non-project chats). Default offset is 1 (1-based), limit 5000 (max 5000), sortby LastModifiedTime, sortorder desc. Optional filterExpression (Title supports wildcards) and projectionExpression. Super-admin callers receive all non-project chats with owner access. No request body.

📄️ Create a new chat

Creates a playground chat titled Untitled Chat, grants the caller owner access, and sets ExpirationTime from the user's ChatExpirationDays (default 30 days). No request body is read. Returns Message and ChatId.

📄️ Get chat details

Returns ChatId, Title, CreationTime, CreatedBy, Keywords, AccessType, and Summary, SummaryGenerationStatus, and Files when present. Files include SyncStatus when enrichment runs. Requires at least read-only access. Code-generator chats (chat_id starts with {user_id}-) use job access instead of chat ACL. No query parameters. No request body.

📄️ Update chat details or trigger summarization

Requires owner access and action. action=update applies Title, Keywords, and/or Visibility from the body (all optional; omitted fields are unchanged). Visibility is project chats only and can only be set to public (cannot change public back to private). Empty or unchanged body returns 'No updates performed.' action=summarize starts summary generation (needs at least 2 messages; body unused).

📄️ Delete a chat

Deletes the chat, its messages, attached files, and ACL. Requires owner access. No request body. Returns 'Chat deleted successfully'.

📄️ List chat messages

Returns a paginated list of messages for the chat. Requires at least read-only access. Default offset is 1 (1-based), limit 5000 (max 5000), sortby MessageTime, sortorder asc (unlike chat list, which defaults to desc). Optional filterExpression (Content supports wildcards) and projectionExpression. Chart Content is replaced with a presigned plot URL. Code-generator chats (chat_id starts with {user_id}-) use job access. No request body.

📄️ List, download, or preview files

Omit action (or any value other than download/preview) to list files. List with chat_id returns that chat's files plus global files (chat_id is used as-is; pass project-files-{project_id} to list a project's files). List without chat_id returns accessible chat, project, and global files. Default offset 1, limit 5000 (max 5000), sortby UploadTime, sortorder desc. action=download or preview requires file_name; chat_id defaults to the user's global files (use global). project_id (not N/A) targets project files. Preview of csv/tsv/txt/json/sql returns {data}; otherwise {PresignedURL}. No request body.

📄️ Get an upload URL or add files to a dataset

action=save_to_dataset copies existing files into a dataset (owner on each source chat; DatasetId and Files required, max 5). Any other action value, or omitting action, returns a presigned PUT URL. Upload body requires FileName; optional ChatId (default global files, or global) or ProjectId (editor; max 10 project files; FileSize max 50 MB). Duplicate names get a (n) suffix.

📄️ Delete a file

Deletes one file from S3 and the Files list. file_name is required. chat_id defaults to the user's global files (use global). project_id (not N/A) deletes from project files instead. Chat/global delete requires owner access. No request body.

📄️ List playground notes accessible to the user

Returns notes the caller can access, with optional Title filtering, sort, pagination, and field projection. Note content is not included; use GET /ai/playground/notes/{note_id} for markdown content.

📄️ Create a playground note or prompt

Creates a note owned by the caller. Title and NoteContent are required. NoteContent is stored as markdown in S3 (max 50000 characters). ProjectLevelAccess is set to none on create.

📄️ Get a playground note including markdown content

Returns the note record plus NoteContent loaded from S3. Requires at least read-only access. Missing NoteType is backfilled to note.

📄️ Update a playground note

Updates Title, NoteContent, Sources, and/or ProjectLevelAccess for a note. Omitted fields are unchanged. Requires editor access. Empty updates return No updates performed.

📄️ Delete a playground note

Deletes the note metadata, ACL, and S3 markdown object. Requires owner access.

📄️ Get chat config

Returns the calling user's stored AIChatsConfig (NotesExpirationDays and ChatExpirationDays). If AIChatsConfig is unset, returns defaults 180 and 30. No query parameters. No request body.

📄️ Set chat config

Updates the calling user's AIChatsConfig. Body may include NotesExpirationDays and/or ChatExpirationDays (0-365). Omitted keys keep the stored value, or 180 / 30 if never set. Extra body fields are ignored. JSON body is required. Returns Message.

📄️ Create a new knowledge base

Creates an unstructured (vector RAG) or structured (SQL) knowledge base in Bedrock and DynamoDB. KnowledgebaseName is required and must be unique. Defaults to unstructured, which also requires EmbeddingModel. Structured requires DataStoreType; TenantName is required for redshift when multi-tenancy is enabled. Account limit is 100 knowledge bases. A 200 response means creation was initiated (unstructured) or datastore setup is in progress (structured).

📄️ List accessible knowledge bases

Returns a paginated list of knowledge bases the authenticated user can access (owner, editor, or read-only). Default offset is 1 (1-based), limit 100 (max 1000), sortby LastModifiedTime, sortorder desc. Optional filterExpression (KnowledgebaseName supports wildcards) and projectionExpression. Structured items omit EmbeddingModel and SmartChunking.

📄️ Get presigned URL for a citation page image

Returns a 1-hour S3 presigned URL for a PDF/DOCX page image used in citation previews. Requires modality=text. FileName must be a catalog path (domain/dataset/.../filename) or a project path (projects/files/{project_id}/{filename} or {project_id}/{filename}). PageNumber is 1-based. The caller must have access to the catalog dataset/file or project, and the page image must already exist.

📄️ Get details of a specific knowledge base

Retrieves a knowledge base by ID, including SourceDetails and the caller's AccessType. Unstructured knowledge bases also include aggregated Metrics. Requires at least read-only access. If status is CREATING or UPDATING, it is refreshed from Bedrock before the response is returned.

📄️ Update an existing knowledge base

Updates Description (required, max 200 characters) and optional GuardRails. If GuardRails is omitted or empty, the default guard rail is applied. KnowledgebaseName cannot be changed. Requires editor access.

📄️ Delete a knowledge base

Deletes a knowledge base and associated resources. Fails if it is still attached to any projects. Structured knowledge bases are deleted synchronously; unstructured ones are set to DELETING and removed asynchronously. Requires owner access. No request body.

📄️ Add a Dataset or Domain source to a knowledge base

Attaches one Dataset or Domain source. Requires editor access on the knowledge base and on the dataset or domain. Unstructured knowledge bases allow at most 5 sources and accept optional ChunkingConfiguration (default NONE) and ParsingConfiguration (default DEFAULT). Structured knowledge bases ignore chunking/parsing; the dataset TargetLocation must match the knowledge base DataStoreType. Datasets must be internal (not Hudi or Iceberg).

📄️ Get file status or metrics for a knowledge base source

Requires action. file_status returns a paginated list of files and per-KB indexing status (default sort FileName, offset 1, limit 100, max 1000). get_metrics returns aggregated Bedrock ingestion Metrics for the source (pagination query params are ignored). Requires at least read-only access. file_status matches SourceDetails.SourceId. get_metrics uses resource_id as the Bedrock data source ID.

📄️ Update a knowledge base datasource description

Updates only the Description of an existing datasource. Requires editor access. Unstructured sources are updated in Bedrock and DynamoDB; structured sources are updated in DynamoDB only. resource_id is the Bedrock SourceId for unstructured sources, or ResourceKey for structured sources.

📄️ Delete a knowledge base datasource

Removes a datasource. Fails if a conflicting sync job is RUNNING. Structured sources are deleted synchronously. Unstructured sources are set to DELETING and removed asynchronously. resource_id is the Bedrock SourceId for unstructured sources, or ResourceKey for structured sources. No request body.

📄️ List sync job runs for a knowledge base

Returns a paginated list of JobRun items for the knowledge base. Default offset is 1 (1-based), limit 100 (max 1000), sortby StartTime, sortorder desc. RUNNING runs with an ExecutionArn are checked against Step Functions and marked FAILED if the execution failed, timed out, or was aborted. KnowledgebaseId and SortKey are stripped from each item. The knowledge base must exist. No request body.

📄️ Start a knowledge base sync job

Starts an asynchronous sync and returns JobRunId. Requires editor access. Unstructured: omit SourceIds to sync all attached sources (ExecutionScope KnowledgeBase). If SourceIds is present, those Bedrock source IDs are synced (ExecutionScope Datasource) and must already be attached. Structured: the body is ignored and the whole knowledge base is synced. Fails if a JobRun is already RUNNING, if no sources are attached, or if an unstructured embedding model is not assigned.

📄️ Query an unstructured knowledge base

Vector-retrieves relevant chunks and generates an answer. Unstructured knowledge bases only. Structured knowledge bases are not queried on this path (they have no embedding model and this handler does not call the structured retrieve-and-generate flow). Requires at least read-only access. modelId must be a TEXT model assigned to knowledge bases. Optional SourceId (Bedrock data source ID) and FileName (source URI) scope retrieval. Citations are not returned on this REST path. Fails if no sources are attached or the embedding model is not assigned.

📄️ List user-accessible AI agents and system agents

Returns AI agents the caller can access (owner, editor, or read-only), plus system agents that are always included. Listing is in-memory: results are filtered, sorted, and paginated in the Lambda. Caller must send a valid role_id. Requires AICore to be enabled (AI-1004 otherwise).

📄️ Create a new custom agent

Creates a CUSTOM AgentCore agent. AgentId must be the value returned by GET /ai/agents?action=upload-script, and the zip package must already be uploaded to that presigned URL. Required body fields: AgentId, AgentName, ModelId, Description, PythonVersion, EntryPoint, AgentType (CUSTOM).

📄️ Get AI agent details, package URLs, or logs

Default (no action): returns details for agent {id}. CUSTOM agents require at least read-only resource access. SYSTEM agents are returned with a reduced field set and AccessType read-only. ARN attributes are omitted. CUSTOM agents include ReferenceId when the AgentCore runtime exists.

📄️ Update a custom agent, enable or disable it, or change a system agent model

CUSTOM agents require editor access. Default (no action): validates the body against UpdateAgentRequestBody, sets AgentStatus to UPDATING, and triggers async AgentCore update. If the agent is CREATE_FAILED, async recreate uses the POST creation path. Allowed statuses for update are READY, UPDATE_FAILED, and CREATE_FAILED (AI-1002 otherwise).

📄️ Delete a custom AI agent

Starts deletion of a CUSTOM agent. Caller must be owner. SYSTEM agents cannot be deleted (AI-1002). Agents whose AgentStatus ends with ING (CREATING, UPDATING, DELETING) cannot be deleted (AI-1002). Agents attached to AI projects must be detached first (AI-1003).

📄️ Create an AI guard rail

Creates a Bedrock guard rail and Amorphic metadata. Requires GuardRailName and Description. Maximum 100 guard rails. The creator receives owner access.

📄️ List AI guard rails accessible to the user

Returns guard rails the caller can access, with optional filter, sort, pagination, projection, and component restriction. AICore must be enabled.

📄️ Get AI guard rail details by ID

Returns the latest version of the guard rail with configuration flattened onto the top-level object. Requires at least read-only access.

📄️ Update an existing AI guard rail

Updates Bedrock and DynamoDB configuration for a non-system guard rail. GuardRailName, Tier, and Scope cannot be changed. Requires editor access.

📄️ Delete an AI guard rail

Deletes the Bedrock guard rail and all DynamoDB versions. Blocked for system-created rails or rails still attached to resources or component configurations. Requires owner access.

📄️ Set a global AI guard rail as the organization default

Marks this global guard rail as default (IsDefault true) and unsets the previous default. Private rails cannot be default. Requires at least read-only access.

📄️ Test a prompt against an AI guard rail

Applies the guard rail to InputText. When InvokeModel is false (default), only apply_guardrail runs. When true, the model is invoked with the guard rail attached. Requires at least read-only access.

📄️ Get the organization default AI guard rail

Returns the default guard rail with Configuration nested. Falls back to SYSTEM-Standard when no user default is set. Requires ai.view and AICore.

📄️ Create an Automated Reasoning policy

Creates a Bedrock Automated Reasoning policy and Amorphic metadata. Name and Description are required. PolicyDefinition is optional and stored in S3 when provided. The creator receives owner access.

📄️ List Automated Reasoning policies accessible to the user

Returns policies the caller can access, with optional PolicyName filtering, sort, pagination, and field projection. AICore must be enabled.

📄️ Get Automated Reasoning policy details

Returns the policy record. Optional projectionExpression limits returned attributes. Requires at least read-only access.

📄️ Update a draft Automated Reasoning policy

Updates the Bedrock draft policy and Amorphic metadata. PolicyDefinition is required in the OpenAPI schema. Name and Description are optional. Requires editor access.

📄️ Delete an Automated Reasoning policy

Deletes the policy from Amorphic, Bedrock, and related S3 objects. Rejected when GuardRailIds is non-empty. Requires owner access.

📄️ List build workflows for an Automated Reasoning policy

Returns the BuildWorkflows map stored on the policy. Requires at least read-only access.

📄️ Start a policy build workflow or generate an upload URL

Starts IMPORT_POLICY or INGEST_CONTENT. Set action=generate_presigned_url to receive a PUT URL for the workflow file instead of starting the workflow. A policy may have at most two build workflows. Requires owner access.

📄️ Get build workflow details or export its document

Returns stored workflow details. Set action=export_document to receive a presigned GET URL for the workflow document instead.

📄️ Cancel or sync an Automated Reasoning build workflow

Omitting action cancels a non-terminal workflow. action=sync applies a completed workflow POLICY_DEFINITION into the policy and marks Approved true. Requires owner access.

📄️ Delete an Automated Reasoning build workflow

Removes the workflow from Bedrock and from the policy BuildWorkflows map, and deletes the uploaded S3 file when FileName is set. Requires owner access.

📄️ Get completed build workflow policy definition

Returns POLICY_DEFINITION assets from Bedrock. The workflow Status must be completed. action is required and currently only POLICY_DEFINITION is supported.

📄️ List AI projects

Returns the AI projects you can access. Super-admins see every project and are treated as owners. Pinned projects are returned separately in `pinnedProjects`, in the order user pinned them, and are not included in `projects`. Each response also includes `recentThreads`, a combined list of recent threads across those projects.

📄️ Create an AI project

Creates a new AI project, or pins or unpins an existing one.

📄️ Get AI project details

Returns one AI project, including its metadata, assistant settings, your access level, linked knowledge bases and agents (with sync status), uploaded files (with indexing status), and when project context was last refreshed.

📄️ 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.

📄️ Delete an AI project

Starts deleting an AI project in the background. You must be an owner of the project.

📄️ Add project stewards

Adds one or more users to the steward list of an AI project. Stewards are the people notified whenever a comment is posted on the project. You must be an owner or editor of the project, and every user you add must already have owner or editor access on it — the whole request is rejected if any of them does not. Adding a user who is already a steward changes nothing and still succeeds.

📄️ Remove project stewards

Removes one or more users from the steward list of an AI project. They keep their access to the project and simply stop receiving comment notifications. You must be an owner or editor of the project. Users in the list who are not stewards are ignored, so the call is safe to repeat. Removing the last steward leaves the project with no stewards, and comments on it then notify nobody.

📄️ List comments on an AI project

Returns the comments left on an AI project, newest first, one page at a time.

📄️ Add a comment to an AI project

Posts a comment on an AI project and returns the identifier of the new comment. You need at least read-only access on the project, so any project member can comment. You are recorded as the author, and the comment is timestamped server-side. Project stewards are notified by email and push notification; if notification fails the comment is still saved and the call still succeeds.

📄️ Delete a comment from an AI project

Permanently removes one comment from an AI project. You can delete a comment if you wrote it, or if you are an owner or editor of the project. Deletion cannot be undone, and deleting a comment that no longer exists is rejected rather than treated as a no-op.

📄️ List threads in a project

Returns the conversation threads in a project that you are allowed to see: the threads you created, plus any thread another member has shared as public. You need at least read-only access to the project. Results are paged. Increase `offset` by `limit` while `next_available` is the string 'yes' and stop when it is 'no'.

📄️ Create a thread in a project

Starts a new conversation thread in a project and returns its identifier. You need at least read-only access to the project. The call takes no request body. The thread is created with the title 'New Thread' and visibility `private`, and you become its owner; rename it or share it afterwards with the thread update endpoint. It also joins the project's RecentThreads list, which keeps the five most recently active threads.

📄️ Get project thread details

Returns everything stored about one thread: its title, keywords, visibility, timestamps, attached files, and the generated summary when one exists. Use the thread messages endpoint for the conversation itself. You need at least read-only access to the project. `AccessType` in the response is `owner` when you created the thread and `read-only` otherwise.