Skip to main content
POST
UploadSkill
Questions or issues? Contact us at api-support@manus.ai.
Auth:
  • API Key: Full access.
  • Standard OAuth client: Not available. Returns permission_denied (HTTP 403) regardless of scopes.
  • Trusted client: Full access.
Project uploads require the user to own the project or be a project member with edit permission.Team uploads require a Team account where the user is a Team Owner, Admin, or Super Admin. Individual users and regular team members receive permission_denied.

Upload flow

  1. Call file.upload with the package’s filename, then PUT the zip bytes to the returned upload_url.
  2. After the PUT completes, call skill.upload with the returned file.id. Choose where the skill goes with scope and project_id; see Target scope.
  3. Use the returned skill.id in message.enable_skills or message.force_skills of task.create or task.sendMessage.
The source file is not consumed. It still expires on the normal file.upload schedule, and deleting it does not affect the skill.

Target scope

Other combinations return 400 invalid_argument. scope values are lowercase and match skill.owner_type in the response. Requests without scope keep working as before. A team upload always targets the team that the API Key’s or token’s user belongs to; there is no team ID parameter.

Package requirements

Same-name uploads

The name in SKILL.md identifies the skill within the target scope: the user’s personal skills, the team’s skill library, or the skills of the given project.

After upload

  • A created or restored personal skill is enabled for the user. Updating an existing personal skill keeps the user’s current enabled state.
  • Every successful project upload adds the skill to the project’s default skills, so it appears in skill_ids of project.detail. This also re-adds a skill that was removed from skill_ids with project.update.
  • A created or restored team skill is not added to team members’ skill lists automatically, including the uploader’s, and is not enabled by default. Members can add it from the team library in Manus, and team admins can change these defaults in Manus. Updating an existing team skill keeps its current team settings.
  • Personal skills appear in skill.list. Pass project_id there to list project skills, or scope=team to list the team library.

Errors

Headers

x-manus-api-key
string

API key for direct authentication. Provide either this or Authorization, not both. See Authentication.

Authorization
string

OAuth2 access token in Bearer {token} format. Only Trusted team client and Trusted public client apps can call this endpoint; standard OAuth clients receive 403 permission_denied regardless of scopes. Provide either this or x-manus-api-key, not both. See the Open App guide.

Example:

"Bearer {access_token}"

Body

application/json
file_id
string
required

ID of a file uploaded with file.upload. The file must belong to the user, have finished uploading, and be a zip skill package of at most 8 MiB (8,388,608 bytes). The file is not consumed: it still expires on the normal file schedule, and deleting it does not affect the skill.

Required string length: 1 - 64
scope
enum<string>

Where to upload the skill. Values match owner_type in the response.

  • personal — the user's personal skills. project_id must be omitted.
  • team — the skill library of the user's team. The user must be a Team Owner, Admin, or Super Admin. project_id must be omitted.
  • project — the project given by project_id, which is required.

When omitted, the skill goes to the project if project_id is set, and to the user's personal skills otherwise.

Available options:
personal,
team,
project
project_id
string

Target project. Required when scope is project; when scope is omitted, setting it uploads the skill to this project instead of the user's personal skills. Must be omitted when scope is personal or team. The user must own the project or be a project member with edit permission. Use project.list to get project IDs.

Required string length: 1 - 65
overwrite
boolean
default:false

When a skill with the same SKILL.md name already exists in the target scope, upload a new version of it instead of returning 409 already_exists. The skill keeps its ID. Uploading a byte-identical package changes nothing.

Response

Skill uploaded successfully.

ok
boolean

Whether the request was successful.

Example:

true

request_id
string

Unique identifier for this API request.

skill
object

The uploaded skill, in the same shape as skill.list. owner_type is personal, team, or project.

created
boolean

true only when a new skill was created. false when an existing skill was updated, a previously deleted skill with the same name was restored with its original ID, or the package was identical to the current version.