技能

上傳技能

POST /api/v1/skills/upload/

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/skills/upload/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@example_file.pdf" \
  -F "attached_tool_ids=範例字串"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');
const FormData = require('form-data');

// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('file', /* 實際檔案物件 */, 'example_file.pdf');
formData.append('attached_tool_ids', '範例字串');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/skills/upload/", formData, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/upload/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# 建立檔案和表單資料
files = {
    'file': ('example_file.pdf', open('example_file.pdf', 'rb'), 'application/pdf'),
    'attached_tool_ids': (None, '範例字串')
}

response = requests.post(url, files=files, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/skills/upload/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.pdf', 'r'),
                'filename' => 'example_file.pdf'
            ],
            [
                'name' => 'attached_tool_ids',
                'contents' => '範例字串'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id"?: string (uuid) // 非必填
  "name"?: string // 非必填
  "description"?: string // 非必填
  "attached_tools"?: [ // 已依技能包 frontmatter 自動綁定的工具名稱 (非必填)
    string
  ]
  "missing_tools"?: [ // 技能包宣告但本組織查無同名工具、需手動補綁的工具名稱 (非必填)
    string
  ]
  "message"?: string // 非必填
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "attached_tools": [
    "回應字串"
  ],
  "missing_tools": [
    "回應字串"
  ],
  "message": "回應字串"
}

狀態碼: 400

回應結構範例

{
  "detail"?: string // 錯誤訊息 (非必填)
}

回應範例值

{
  "detail": "回應字串"
}

---

建立技能

POST /api/v1/skills/

請求內容

請求參數

欄位	類型	必填	說明
name	string	是
description	string	是
whenToUse	string	否	Describe when the LLM should trigger this skill. Max 200 characters recommended.
instructions	string	否	Markdown text with instructions for the skill
attachedToolIds	array[string]	否
groups	array[IdName]	否	Groups this skill is assigned to. Non-owner members must pick at least one group they belong to.
files	array[object]	否	Optional resource files to create with the skill. Each item must include path and content. content_encoding may be "text" or "base64".

請求結構範例

{
  "name": string
  "description": string
  "whenToUse"?: string // Describe when the LLM should trigger this skill. Max 200 characters recommended. (非必填)
  "instructions"?: string // Markdown text with instructions for the skill (非必填)
  "attachedToolIds"?: [ // 非必填
    string (uuid)
  ]
  "groups"?: [ // Groups this skill is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
    {
      "id": string (uuid)
    }
  ]
  "files"?: [ // Optional resource files to create with the skill. Each item must include path and content. content_encoding may be "text" or "base64". (非必填)
    object
  ]
}

請求範例值

{
  "name": "範例名稱",
  "description": "範例字串",
  "whenToUse": "範例字串",
  "instructions": "範例字串",
  "attachedToolIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "files": [
    {}
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/skills/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "description": "範例字串",
    "whenToUse": "範例字串",
    "instructions": "範例字串",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "files": [
      {}
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "description": "範例字串",
    "whenToUse": "範例字串",
    "instructions": "範例字串",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "files": [
      {}
    ]
  };

axios.post("https://api.maiagent.ai/api/v1/skills/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "description": "範例字串",
    "whenToUse": "範例字串",
    "instructions": "範例字串",
    "attachedToolIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "files": [
        {}
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/skills/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'description' => '範例字串',
            'whenToUse' => '範例字串',
            'instructions' => '範例字串',
            'attachedToolIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'files' => [
                new \stdClass()
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description": string
  "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
  "instructions": string // Markdown text with instructions for the skill
  "compatibility": string // Optional environment requirements from the Agent Skills Spec frontmatter (max 500 chars).
  "metadata": object // Optional arbitrary key-value mapping from the Agent Skills Spec frontmatter.
  "allowedTools": object // Optional pre-approved tool list from the Agent Skills Spec frontmatter (experimental).
  "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
  {
  }
  "skillPackagePath": string // S3 path for the uploaded .skill/.zip file
  "skillPackageName": string // Original filename of the uploaded skill package
  "skillPackageSize": integer // Size of the uploaded skill package in bytes
  "skillPackageUploadedAt": string (timestamp)
  "attachedTools": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "resources": [
    {
      "id": string (uuid)
      "path": string // Relative path within the skill directory, e.g. scripts/helper.py
      "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
      "fileSize": integer // File size in bytes
      "mimeType": string
      "createdAt": string (timestamp)
    }
  ]
  "groups": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "lastUsedAt": string (timestamp)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "whenToUse": "回應字串",
  "instructions": "回應字串",
  "compatibility": "回應字串",
  "metadata": null,
  "allowedTools": null,
  "source": {},
  "skillPackagePath": "回應字串",
  "skillPackageName": "回應字串",
  "skillPackageSize": 456,
  "skillPackageUploadedAt": "回應字串",
  "attachedTools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "resources": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "回應字串",
      "filePath": "回應字串",
      "fileSize": 456,
      "mimeType": "回應字串",
      "createdAt": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "createdAt": "回應字串",
  "updatedAt": "回應字串",
  "lastUsedAt": "回應字串",
  "canUpdate": false,
  "canDelete": false
}

---

列出技能

GET /api/v1/skills/

參數

參數名稱	必填	類型	說明
isActive	❌	boolean
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
search	❌	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/?isActive=true&page=1&pageSize=1&search=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/?isActive=true&page=1&pageSize=1&search=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/?isActive=true&page=1&pageSize=1&search=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/?isActive=true&page=1&pageSize=1&search=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
      "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
      {
      }
      "attachedTools": [
        {
          "id": string (uuid)
          "name": string
          "description": string
          "displayName": string
          "toolType": string
        }
      ]
      "groups": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "createdBy": object // Show 'System' as the creator for global skills (uploaded by platform staff).
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
      "lastUsedAt": string (timestamp)
      "canUpdate": boolean // Return whether the current user can update this resource.
      "canDelete": boolean // Return whether the current user can delete this resource.
    }
  ]
}

回應範例值

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "whenToUse": "回應字串",
      "source": {},
      "attachedTools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "description": "回應字串",
          "displayName": "回應字串",
          "toolType": "回應字串"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "createdBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      },
      "createdAt": "回應字串",
      "updatedAt": "回應字串",
      "lastUsedAt": "回應字串",
      "canUpdate": false,
      "canDelete": false
    }
  ]
}

---

取得特定技能

GET /api/v1/skills/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Skill.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description": string
  "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
  "instructions": string // Markdown text with instructions for the skill
  "compatibility": string // Optional environment requirements from the Agent Skills Spec frontmatter (max 500 chars).
  "metadata": object // Optional arbitrary key-value mapping from the Agent Skills Spec frontmatter.
  "allowedTools": object // Optional pre-approved tool list from the Agent Skills Spec frontmatter (experimental).
  "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
  {
  }
  "skillPackagePath": string // S3 path for the uploaded .skill/.zip file
  "skillPackageName": string // Original filename of the uploaded skill package
  "skillPackageSize": integer // Size of the uploaded skill package in bytes
  "skillPackageUploadedAt": string (timestamp)
  "attachedTools": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "resources": [
    {
      "id": string (uuid)
      "path": string // Relative path within the skill directory, e.g. scripts/helper.py
      "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
      "fileSize": integer // File size in bytes
      "mimeType": string
      "createdAt": string (timestamp)
    }
  ]
  "groups": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "lastUsedAt": string (timestamp)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "whenToUse": "回應字串",
  "instructions": "回應字串",
  "compatibility": "回應字串",
  "metadata": null,
  "allowedTools": null,
  "source": {},
  "skillPackagePath": "回應字串",
  "skillPackageName": "回應字串",
  "skillPackageSize": 456,
  "skillPackageUploadedAt": "回應字串",
  "attachedTools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "resources": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "回應字串",
      "filePath": "回應字串",
      "fileSize": 456,
      "mimeType": "回應字串",
      "createdAt": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "createdAt": "回應字串",
  "updatedAt": "回應字串",
  "lastUsedAt": "回應字串",
  "canUpdate": false,
  "canDelete": false
}

---

更新技能

PUT /api/v1/skills/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Skill.

請求內容

請求參數

欄位	類型	必填	說明
name	string	是
description	string	是
whenToUse	string	否	Describe when the LLM should trigger this skill. Max 200 characters recommended.
instructions	string	否	Markdown text with instructions for the skill
attachedToolIds	array[string]	否
groups	array[IdName]	否	Groups this skill is assigned to. Non-owner members must pick at least one group they belong to.

請求結構範例

{
  "name": string
  "description": string
  "whenToUse"?: string // Describe when the LLM should trigger this skill. Max 200 characters recommended. (非必填)
  "instructions"?: string // Markdown text with instructions for the skill (非必填)
  "attachedToolIds"?: [ // 非必填
    string (uuid)
  ]
  "groups"?: [ // Groups this skill is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
    {
      "id": string (uuid)
    }
  ]
}

請求範例值

{
  "name": "範例名稱",
  "description": "範例字串",
  "whenToUse": "範例字串",
  "instructions": "範例字串",
  "attachedToolIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "description": "範例字串",
    "whenToUse": "範例字串",
    "instructions": "範例字串",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "description": "範例字串",
    "whenToUse": "範例字串",
    "instructions": "範例字串",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  };

axios.put("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "description": "範例字串",
    "whenToUse": "範例字串",
    "instructions": "範例字串",
    "attachedToolIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ]
}

response = requests.put(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'description' => '範例字串',
            'whenToUse' => '範例字串',
            'instructions' => '範例字串',
            'attachedToolIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description": string
  "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
  "instructions": string // Markdown text with instructions for the skill
  "compatibility": string // Optional environment requirements from the Agent Skills Spec frontmatter (max 500 chars).
  "metadata": object // Optional arbitrary key-value mapping from the Agent Skills Spec frontmatter.
  "allowedTools": object // Optional pre-approved tool list from the Agent Skills Spec frontmatter (experimental).
  "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
  {
  }
  "skillPackagePath": string // S3 path for the uploaded .skill/.zip file
  "skillPackageName": string // Original filename of the uploaded skill package
  "skillPackageSize": integer // Size of the uploaded skill package in bytes
  "skillPackageUploadedAt": string (timestamp)
  "attachedTools": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "resources": [
    {
      "id": string (uuid)
      "path": string // Relative path within the skill directory, e.g. scripts/helper.py
      "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
      "fileSize": integer // File size in bytes
      "mimeType": string
      "createdAt": string (timestamp)
    }
  ]
  "groups": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "lastUsedAt": string (timestamp)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "whenToUse": "回應字串",
  "instructions": "回應字串",
  "compatibility": "回應字串",
  "metadata": null,
  "allowedTools": null,
  "source": {},
  "skillPackagePath": "回應字串",
  "skillPackageName": "回應字串",
  "skillPackageSize": 456,
  "skillPackageUploadedAt": "回應字串",
  "attachedTools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "resources": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "回應字串",
      "filePath": "回應字串",
      "fileSize": 456,
      "mimeType": "回應字串",
      "createdAt": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "createdAt": "回應字串",
  "updatedAt": "回應字串",
  "lastUsedAt": "回應字串",
  "canUpdate": false,
  "canDelete": false
}

---

部分更新技能

PATCH /api/v1/skills/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Skill.

請求內容

請求參數

欄位	類型	必填	說明
name	string	否
description	string	否
whenToUse	string	否	Describe when the LLM should trigger this skill. Max 200 characters recommended.
instructions	string	否	Markdown text with instructions for the skill
attachedToolIds	array[string]	否
groups	array[IdName]	否	Groups this skill is assigned to. Non-owner members must pick at least one group they belong to.

請求結構範例

{
  "name"?: string // 非必填
  "description"?: string // 非必填
  "whenToUse"?: string // Describe when the LLM should trigger this skill. Max 200 characters recommended. (非必填)
  "instructions"?: string // Markdown text with instructions for the skill (非必填)
  "attachedToolIds"?: [ // 非必填
    string (uuid)
  ]
  "groups"?: [ // Groups this skill is assigned to. Non-owner members must pick at least one group they belong to. (非必填)
    {
      "id": string (uuid)
    }
  ]
}

請求範例值

{
  "name": "範例名稱",
  "description": "範例字串",
  "whenToUse": "範例字串",
  "instructions": "範例字串",
  "attachedToolIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "description": "範例字串",
    "whenToUse": "範例字串",
    "instructions": "範例字串",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "description": "範例字串",
    "whenToUse": "範例字串",
    "instructions": "範例字串",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  };

axios.patch("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
    "name": "範例名稱",
    "description": "範例字串",
    "whenToUse": "範例字串",
    "instructions": "範例字串",
    "attachedToolIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ]
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => '範例名稱',
            'description' => '範例字串',
            'whenToUse' => '範例字串',
            'instructions' => '範例字串',
            'attachedToolIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id": string (uuid)
  "name": string
  "description": string
  "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
  "instructions": string // Markdown text with instructions for the skill
  "compatibility": string // Optional environment requirements from the Agent Skills Spec frontmatter (max 500 chars).
  "metadata": object // Optional arbitrary key-value mapping from the Agent Skills Spec frontmatter.
  "allowedTools": object // Optional pre-approved tool list from the Agent Skills Spec frontmatter (experimental).
  "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
  {
  }
  "skillPackagePath": string // S3 path for the uploaded .skill/.zip file
  "skillPackageName": string // Original filename of the uploaded skill package
  "skillPackageSize": integer // Size of the uploaded skill package in bytes
  "skillPackageUploadedAt": string (timestamp)
  "attachedTools": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "resources": [
    {
      "id": string (uuid)
      "path": string // Relative path within the skill directory, e.g. scripts/helper.py
      "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
      "fileSize": integer // File size in bytes
      "mimeType": string
      "createdAt": string (timestamp)
    }
  ]
  "groups": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "lastUsedAt": string (timestamp)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "whenToUse": "回應字串",
  "instructions": "回應字串",
  "compatibility": "回應字串",
  "metadata": null,
  "allowedTools": null,
  "source": {},
  "skillPackagePath": "回應字串",
  "skillPackageName": "回應字串",
  "skillPackageSize": 456,
  "skillPackageUploadedAt": "回應字串",
  "attachedTools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "resources": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "回應字串",
      "filePath": "回應字串",
      "fileSize": 456,
      "mimeType": "回應字串",
      "createdAt": "回應字串"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "createdAt": "回應字串",
  "updatedAt": "回應字串",
  "lastUsedAt": "回應字串",
  "canUpdate": false,
  "canDelete": false
}

---

刪除技能

DELETE /api/v1/skills/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Skill.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼	說明
204	No response body

---

匯出技能

GET /api/v1/skills/{id}/export/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Skill.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/export/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/export/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/export/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/export/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼	說明
200	.skill 檔案下載

---

瀏覽技能包目錄結構

GET /api/v1/skills/{id}/package-structure/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Skill.
path	❌	string	要瀏覽的目錄路徑（預設為根目錄）

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/package-structure/?path=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/package-structure/?path=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/package-structure/?path=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/package-structure/?path=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "package_name"?: string // 技能包檔案名稱 (非必填)
  "package_size"?: integer // 技能包大小（bytes） (非必填)
  "uploaded_at"?: string (date-time) // 上傳時間 (非必填)
  "current_path"?: string // 目前瀏覽路徑 (非必填)
  "items"?: [ // 目錄內容（資料夾優先，依字母排序） (非必填)
    {
      "name"?: string // 檔案或資料夾名稱 (非必填)
      "type"?: string (enum: file, dir) // 項目類型 (非必填)
      "size"?: integer // 檔案大小（bytes），僅 type=file 時回傳 (非必填)
      "item_count"?: integer // 資料夾內直接子項目數量，僅 type=dir 時回傳 (非必填)
    }
  ]
}

回應範例值

{
  "package_name": "回應字串",
  "package_size": 456,
  "uploaded_at": "2025-01-01T00:00:00.000Z",
  "current_path": "回應字串",
  "items": [
    {
      "name": "回應字串",
      "type": "file",
      "size": 456,
      "item_count": 456
    }
  ]
}

狀態碼: 400

回應結構範例

{
  "detail"?: string // 錯誤訊息 (非必填)
}

回應範例值

{
  "detail": "回應字串"
}

---

重新上傳技能

POST /api/v1/skills/{id}/reupload/

參數

參數名稱	必填	類型	說明
id	✅	string	A UUID string identifying this Skill.

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/reupload/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@example_file.pdf"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');
const FormData = require('form-data');

// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('file', /* 實際檔案物件 */, 'example_file.pdf');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/reupload/", formData, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/reupload/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# 建立檔案和表單資料
files = {
    'file': ('example_file.pdf', open('example_file.pdf', 'rb'), 'application/pdf')
}

response = requests.post(url, files=files, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/reupload/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.pdf', 'r'),
                'filename' => 'example_file.pdf'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

{
  "id"?: string (uuid) // 非必填
  "name"?: string // 非必填
  "description"?: string // 非必填
  "message"?: string // 非必填
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "description": "回應字串",
  "message": "回應字串"
}

狀態碼: 400

回應結構範例

{
  "detail"?: string // 錯誤訊息 (非必填)
}

回應範例值

{
  "detail": "回應字串"
}

---

列出技能資源

GET /api/v1/skills/{skillPk}/resources/

參數

參數名稱	必填	類型	說明
skillPk	✅	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 200

回應結構範例

[
  {
    "id": string (uuid)
    "path": string // Relative path within the skill directory, e.g. scripts/helper.py
    "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
    "fileSize": integer // File size in bytes
    "mimeType": string
    "createdAt": string (timestamp)
  }
]

回應範例值

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "path": "回應字串",
    "filePath": "回應字串",
    "fileSize": 456,
    "mimeType": "回應字串",
    "createdAt": "回應字串"
  }
]

---

上傳技能資源

POST /api/v1/skills/{skillPk}/resources/

參數

參數名稱	必填	類型	說明
skillPk	✅	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@example_file.pdf" \
  -F "path=範例字串"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');
const FormData = require('form-data');

// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('file', /* 實際檔案物件 */, 'example_file.pdf');
formData.append('path', '範例字串');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/", formData, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# 建立檔案和表單資料
files = {
    'file': ('example_file.pdf', open('example_file.pdf', 'rb'), 'application/pdf'),
    'path': (None, '範例字串')
}

response = requests.post(url, files=files, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.pdf', 'r'),
                'filename' => 'example_file.pdf'
            ],
            [
                'name' => 'path',
                'contents' => '範例字串'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼: 201

回應結構範例

{
  "id": string (uuid)
  "path": string // Relative path within the skill directory, e.g. scripts/helper.py
  "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
  "fileSize": integer // File size in bytes
  "mimeType": string
  "createdAt": string (timestamp)
}

回應範例值

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "回應字串",
  "filePath": "回應字串",
  "fileSize": 456,
  "mimeType": "回應字串",
  "createdAt": "回應字串"
}

狀態碼: 400

回應結構範例

{
  "path"?: string // 路徑驗證錯誤 (非必填)
  "file"?: string // 檔案驗證錯誤 (非必填)
}

回應範例值

{
  "path": "回應字串",
  "file": "回應字串"
}

---

刪除技能資源

DELETE /api/v1/skills/{skillPk}/resources/{id}/

參數

參數名稱	必填	類型	說明
id	✅	string
skillPk	✅	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼	說明
204	No response body

---

下載技能資源

GET /api/v1/skills/{skillPk}/resources/{id}/download/

參數

參數名稱	必填	類型	說明
id	✅	string
skillPk	✅	string

程式碼範例

Shell/Bash

# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/download/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。

JavaScript

const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/download/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/download/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/download/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>

回應內容

狀態碼	說明
200	檔案下載

---