Powered by

# APIs

# Overview

The Purple Fabric API serves as a high-performance, RESTful interface designed to seamlessly integrate advanced AI capabilities into your applications, services, and workflows. With a strong focus on security, performance, and real-time data processing, the Purple Fabric API is tailored for enterprises and innovators looking to harness AI at scale, empowering teams to build smarter solutions faster.

# API as a Tool

An API Tool enables you to connect and interact with external services through HTTP requests. It supports standard methods such as GET, POST, PUT, and DELETE, enabling seamless data exchange between the platform and third-party APIs. This tool is ideal for integrations, fetching remote data, or triggering actions in external systems.

Rule for API Tool Creation

  • The API Tool accepts the following fields:

    • Method - HTTP method (e.g., GET, POST, PUT, DELETE)
      • GET: Retrieves existing information, such as fetching a specific AI agent’s configuration or downloading a generated compliance report.
      • POST: Creates a new resource or triggers an action, such as submitting a query to the Knowledge Garden or initiating a workflow.
      • PUT: Updates or replaces an existing resource entirely, such as rotating an API access key or updating a persona's complete instruction set.
      • DELETE: Removes a resource from the system, such as removing an unwanted agent
    • URL - Full endpoint URL
    • Headers - Optional HTTP headers in key-value format
    • Body - Request body (optional)
    • Parameters - Static query parameters (key-value pairs defined at design time: dynamic parameters are not yet supported)

  • The Body supports only one type per request. You can choose from:

    • JSON
    • Formdata
    • None

  • If the Body is defined as json or formdata, you must provide a sample schema that outlines the expected structure of the body. This schema helps ensure proper formatting and understanding of the request body’s contents.

  • Sample Schema - When using json or formdata as the body type, always include an example schema to define the structure of the data. This ensures consistency in how data is formatted and parsed.

Make sure to structure your input accordingly to avoid conflicts and ensure compatibility.

Sample API Tool UI

Refer to the following APIs:

  1. Conversation Agent APIs
  2. Automation Agent APIs

# 1. Conversation Agent APIs

  1. Getting Access Token API
  2. Agents API
  3. Creating a New Conversation Agent API
  4. Updating a Conversation Agent API
  5. Deleting a Conversation Agent API

# Getting Access Token API - Authentication & Authorization

Access Token API serves as the primary security gatekeeper for the Purple Fabric platform.
Request Method - GET
Gateway URL - https:///accesstoken/

# Request Headers

Key Value
API key apikey
Username username
Password password
Content-Type application/json

# Request Body

Not required for this request.

# Sample Response

STATUS - 200 - application/json

{
   "result": "RESULT_SUCCESS",
   "active": true,
   "access_token": "eyJhbGciOiJSUzI1NiI....",
   "expires_in": "3600",
   "refresh_token": "eyJhbGciOiJIUzI1....",
   "refresh_expires_in": "1800"
}

STATUS - 401 - unauthorized

{
   "result": "RESULT_FAILURE",
   "message": "401 Unauthorized: [no body]",
   "active": false
}

# Agents API

API to list the existing agents for the Logged In User (Private, public, subscribed,global(org level) public).
Request Method - POST
Gateway URL - https:///magicplatform/v1/assets

# Request Headers

Key Value
API key apikey
Username username
Password password
Content-Type application/json

# Request Body 

query {
  assets(
    downloadImages: true
    assetInput: {
      filterLevel: { Organization: [private, public, subscribed] }
      sortFilters: { modified_date: DESC }
      commonfilters: { created_by: [], status: [] }
      assetFlags: {
        getAssetFeature: true
        getDeprecatedAssetsCount: true
        getLatestAssetVersion: true
      }
      assetFilters: {
        agent_type: []
        categories: [GENAI, WORKFLOW]
        sub_categories: [AUTOMATION, CONVERSATION, NEW]
      }
      searchFilter: ""
      getCurrentUserAssets: false
    }
    paginate: { page: 1, limit: 12 }
  ) {
    meta {
      itemCount
      totalItems
      itemsPerPage
      totalPages
      currentPage
      deprecatedAssetsCount
    }
    items {
      features {
        feature_id
        feature
        display_name
        description
        featureConfig {
          feature_config_id
          is_secret
          key
          value
          properties
          data_type
        }
        input_schema_data {
          entities {
            properties
          }
        }
      }
      auto_annotate {
        auto_annotation_id
        status
        abort_reason
        auto_annotation_version
        total_selected
        processed
      }
      documents {
        base64
        file_id
      }
      name
      display_name
      category
      sub_category
      asset_id
      asset_version_id
      description
      version
      tags
      tag_details {
        tag_id
        tag_name
        tag_type
      }
      published_by
      ui_component_url
      status
      spec_version
      is_public
      is_private
      skill_visibility
      created_date
      created_by
      modified_by
      modified_date
      subscription_id
      subscription_status
      subscribed_by_id
      user_id
      fabric_profile_id
      last_name
      first_name
      org_id
      org_name
      owner
      sub_category
      agent_type
      has_other_version
      is_file_mandatory
    }
  }
}

# Sample Response

STATUS - 200 - application/json

{
    "data": {
        "assets": {
            "meta": {
                "itemCount": 12,
                "totalItems": 1027,
                "itemsPerPage": 12,
                "totalPages": 86,
                "currentPage": 1,
                "deprecatedAssetsCount": 2
            },
            "items": [ 
                {
                    "features": [
                        {
                            "feature_id": "4a31475d-1555-460a-9655-d87a5745cf8e",
                            "feature": "genai",
                            "display_name": "genai",
                            "description": null,
                            "featureConfig": [],
                            "input_schema_data": {
                                "entities": []
                            }
                        }
                    ],
                    "auto_annotate": null,
                    "documents": null,
                    "name": "TC_GenAI_249_260227_0255",
                    "display_name": "TC_GenAI_249_260227_0255",
                    "category": "GENAI",
                    "sub_category": "CONVERSATION",
                    "asset_id": "8e64c28e-836c-4e33-8746-ba2f859045d8",
                    "asset_version_id": "8437c105-339d-473b-99ca-e7248327afde",
                    "description": "Create a GenAI conversation asset - Default",
                    "version": "1.0",
                    "tags": [
                        "genai"
                    ],
                    "tag_details": null,
                    "published_by": null,
                    "ui_component_url": null,
                    "status": "PUBLISHED",
                    "spec_version": "2.0",
                    "is_public": false,
                    "is_private": false,
                    "skill_visibility": "WORKSPACE",
                    "created_date": "2026-02-27T02:56:55.917Z",
                    "created_by": "033000fb-3de1-4ae4-b448-b49340e41eef",
                    "modified_by": null,
                    "modified_date": "2026-02-27T03:11:21.892Z",
                    "subscription_id": null,
                    "subscription_status": null,
                    "subscribed_by_id": null,
                    "user_id": "033000fb-3de1-4ae4-b448-b49340e41eef",
                    "fabric_profile_id": "idxsandbox-user-9037353130",
                    "last_name": "Test",
                    "first_name": "Automation",
                    "org_id": "baeb5ece-684f-4f08-8832-7286daae1f62",
                    "org_name": "idxsandbox",
                    "owner": "Automation Test",
                    "agent_type": "SINGLE_AGENT",
                    "has_other_version": false,
                    "is_file_mandatory": false
                },
                {
                    "features": [
                        {
                            "feature_id": "a438d978-c285-40db-88b1-3d62f29b56a0",
                            "feature": "genai",
                            "display_name": "genai",
                            "description": null,
                            "featureConfig": [],
                            "input_schema_data": {
                                "entities": []
                            }
                        }
                    ],
                    "auto_annotate": null,
                    "documents": null,
                    "name": "TC_GenAI_025_260227_0255",
                    "display_name": "TC_GenAI_025_260227_0255",
                    "category": "GENAI",
                    "sub_category": "CONVERSATION",
                    "asset_id": "80c37934-7e65-49b7-9cd7-da809f9671c2",
                    "asset_version_id": "fea07e7b-4b16-4e20-b9fe-ad78a7b1fa45",
                    "description": "RAG Description",
                    "version": "1.0",
                    "tags": [
                        "genai"
                    ],
                    "tag_details": null,
                    "published_by": null,
                    "ui_component_url": null,
                    "status": "PUBLISHED",
                    "spec_version": "2.0",
                    "is_public": false,
                    "is_private": false,
                    "skill_visibility": "NONE",
                    "created_date": "2026-02-27T02:59:00.937Z",
                    "created_by": "033000fb-3de1-4ae4-b448-b49340e41eef",
                    "modified_by": null,
                    "modified_date": "2026-02-27T03:01:07.938Z",
                    "subscription_id": null,
                    "subscription_status": null,
                    "subscribed_by_id": null,
                    "user_id": "033000fb-3de1-4ae4-b448-b49340e41eef",
                    "fabric_profile_id": "idxsandbox-user-9037353130",
                    "last_name": "Test",
                    "first_name": "Automation",
                    "org_id": "baeb5ece-684f-4f08-8832-7286daae1f62",
                    "org_name": "idxsandbox",
                    "owner": "Automation Test",
                    "agent_type": "SINGLE_AGENT",
                    "has_other_version": false,
                    "is_file_mandatory": false
                }
            ]
        }
    }
}

# Creating a New Conversation Agent API

API to create a new Conversation Agent
Request Method - POST
Gateway URL - https:///magicplatform/v1/assets

# Request Headers

Key Value
Authorization Bearer
Content-Type application/json

# Request Body 

query {
mutation {
    createAsset(createAssetInput: {
        createAssetAndVersion: {
            versionDetail: {
                description: "Provides finance related support",
                status: INITIATED,
                display_name: "Finance Help",
                is_private: true
            },
            assetDetail: {
                name: "Finance Help",
                category: GENAI,
                sub_category: CONVERSATION,
                agent_type: SINGLE_AGENT
            }
        }
    }) {
        asset_version_id
        created_date
        modified_date
        is_private
        asset {
            sub_category
        }
    }
}
}

# Sample Response

STATUS - 200 - application/json

{
    "data": {
        "createAsset": {
            "asset_version_id": "b10ad5ae-67b2-476a-bd13-9881189194e4",
            "created_date": "2026-03-03T10:47:08.429Z",
            "modified_date": "2026-03-03T10:47:08.429Z",
            "is_private": true,
            "asset": {
                "sub_category": "CONVERSATION"
            }
        }
    }
}

# Updating a Conversation Agent API

API to update a conversation agent
Request Method - POST
Gateway URL - https:///magicplatform/v1/assets

# Request Headers

Key Value
Authorization Bearer
Content-Type application/json

# Request Body 

query {
mutation {
  updateAsset(
    updateAssetInput: { status: CREATION_IN_PROGRESS }
    asset_version_id: "35b4dc07-e012-4348-a910-69610a7ea49a"
  ) {
    asset {
      name
      category
    }
    asset_version_id
    status
    display_name
    is_private
    skill_visibility
    assetRun {
      asset_run_id
      run_no
      run_id
      run_type
      status
    }
    asset_latest_run {
      asset_run_id
      run_no
      run_id
      run_type
      status
    }
  }
}}

# Sample Response

STATUS - 200 - application/json

{
    "data": {
        "updateAsset": {
            "asset": {
                "name": "Finance Chat Assistant",
                "category": "GENAI"
            },
            "asset_version_id": "35b4dc07-e012-4348-a910-69610a7ea49a",
            "status": "CREATION_IN_PROGRESS",
            "display_name": "Finance Chat Assistant",
            "is_private": true,
            "skill_visibility": "NONE",
            "assetRun": [
                {
                    "asset_run_id": "68e5b399-2f6a-4e6a-9257-1cc5b15b6c07",
                    "run_no": 1,
                    "run_id": null,
                    "run_type": "CHUNKING",
                    "status": "CREATED"
                }
            ],
            "asset_latest_run": {
                "asset_run_id": "68e5b399-2f6a-4e6a-9257-1cc5b15b6c07",
                "run_no": 1,
                "run_id": null,
                "run_type": "CHUNKING",
                "status": "CREATED"
            }
        }
    }
}

# Deleting a Conversation Agent API

Request Method - POST
URL - https:///magicplatform/v1/assets

# Request Headers

Key Value
Authorization Bearer
Content-Type application/json

# Request Body 

query {
mutation {
  deleteAssetVersion(
    asset_version_id: "35b4dc07-e012-4348-a910-69610a7ea49a"
    force_delete: false
  ) {
    asset_delete_status
    deletion_detail {
      annotation
      mlopshousekeeping
      mlopsschema
    }
  }
}
}

# Sample Response

STATUS - 200 - application/json

{
    "data": {
        "deleteAssetVersion": {
            "asset_delete_status": "SUCCESS",
            "deletion_detail": {
                "annotation": null,
                "mlopshousekeeping": true,
                "mlopsschema": null
            }
        }
    }
}

# 2. Automation Agent APIs

  1. Getting Access Token API
  2. Creating an Automation Agent API

# Getting Access Token API - Authentication & Authorization

Access Token API serves as the primary security gatekeeper for the Purple Fabric platform.
Request Method - GET
Gateway URL - https:///accesstoken/

# Request Headers

Key Value
API key apikey
Username username
Password password
Content-Type application/json

# Request Body

Not required for this request.

# Sample Response

STATUS - 200 - application/json

{
   "result": "RESULT_SUCCESS",
   "active": true,
   "access_token": "eyJhbGciOiJSUzI1NiI....",
   "expires_in": "3600",
   "refresh_token": "eyJhbGciOiJIUzI1....",
   "refresh_expires_in": "1800"
}

STATUS - 401 - unauthorized

{
   "result": "RESULT_FAILURE",
   "message": "401 Unauthorized: [no body]",
   "active": false
}

# Creating an Automation Agent API

Request Method - POST
URL - https:///magicplatform/v1/assets

# Request Headers

Key Value
Authorization Bearer
Content-Type application/json

# Request Body 

query {
mutation {
    createAsset(createAssetInput: {
        createAssetAndVersion: {
            versionDetail: {
                description: "Credit Decisioning Audition",
                status: INITIATED,
                display_name: "Credit Decisioning Auditor",
                is_private: true
            },
            assetDetail: {
                name: "Credit Decisioning Auditor",
                category: GENAI,
                sub_category: AUTOMATION,
                agent_type: SINGLE_AGENT
            }
        }
    }) {
        asset_version_id
        created_date
        modified_date
        is_private
        asset {
            sub_category
        }
    }
}
}

# Sample Response

STATUS - 200 - application/json

{
    "data": {
        "createAsset": {
            "asset_version_id": "df2f01b0-2c42-42da-a76b-0d960e3ddbfe",
            "created_date": "2026-03-03T10:27:48.307Z",
            "modified_date": "2026-03-03T10:27:48.307Z",
            "is_private": true,
            "asset": {
                "sub_category": "AUTOMATION"
            }
        }
    }
}

# Agent Input Parameters Details

Field Allowed Values Description
category GENAI, EXTRACTOR, CLASSIFIER, WORKFLOW, KNOWLEDGEBASE, etc. For AI agents, always use GENAI
sub_category AUTOMATION, CONVERSATION, GENERIC, API, MCP, etc. Use AUTOMATION while creating automation agents or CONVERSATION for conversation agents
agent_type SINGLE_AGENT, MULTI_AGENT Specifies if the agent operates alone or as part of a multi-agent system
is_private true, false Determines if the asset is restricted to the owner or visible to the org
status INITIATED, DESIGN_IN_PROGRESS, CREATION_IN_PROGRESS Defines the current lifecycle stage of the asset version

# Error Codes

Error Code Error Message
401 Request failed
500 Internal Server Error
409 duplicate key value violates unique constraint
NA Query Validation Failed
NA User Not Found
404 Latest version not found
400 Asset Not Published