Imports

An import moves a local project into a workspace as a new cloud project. It is a three-step protocol — create, upload the bundle, finalize — so the manifest, the bundle hash and the protected data are all bound to one reviewed scan.

See the OpenAPI document for schemas and operation IDs.

Prerequisites

• Protected operations require an API key in x-api-key or a browser session cookie; some actions require a verified user session
• Tenant-scoped operations use X-Organization-Id; browser sessions can use their active workspace. Discovery and personal-workspace bootstrap do not require an active workspace
• The base URL for your deployment, https://server.hlix.ai by default

Operations

Method	Path	Operation
POST	/v1/api/projects/{id}/resources/agent	Create a project-scoped agent from local instructions
POST	/v1/api/projects/{id}/resources/mcp	Explicitly activate a validated MCP server for one project
POST	/v1/api/projects/{id}/resources/skill	Activate a skill for one project

Create a project-scoped agent from local instructions

POST /v1/api/projects/{id}/resources/agent · operation ID importProjectAgent

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, ImportAgent (required)

Property	Type	Required	Notes
coder	claude-code | codex | opencode | goose | qwen-code | pi | hlix | null	no
description	string	no	max length 2000
duty	build | triage	no
instructions	string	yes	min length 1, max length 20000
name	string	yes	min length 1, max length 120

Responses

Status	Body	Description
201	ImportedAgent	The project-scoped agent was created.
400	ValidationError | ApiError	The JSON body failed schema validation (ValidationError), or the request named no active organization (ApiError).
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
409	ApiError	The agent name is already taken, or the manifest declares a second triage agent for this scope.

Explicitly activate a validated MCP server for one project

POST /v1/api/projects/{id}/resources/mcp · operation ID importProjectMcp

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, ImportMcp (required)

Property	Type	Required	Notes
args	string[]	no
command	string	no	max length 100
envKeys	string[]	no
headers	object	no
name	string	yes	min length 1, max length 100
transport	stdio | http | sse	yes
url	string (uri)	no	max length 2000

Responses

Status	Body	Description
201	ImportedMcp	The MCP server was activated with secret references.
400	ValidationError | ApiError	The JSON body failed schema validation (ValidationError), or the request named no active organization (ApiError).
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Activate a skill for one project

POST /v1/api/projects/{id}/resources/skill · operation ID importProjectSkill

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, ImportSkill (required)

Property	Type	Required	Notes
content	string	yes	min length 1, max length 200000
slug	string	yes	min length 1, max length 100

Responses

Status	Body	Description
201	ImportedSkill	The skill is available in this project’s Cloud Machine.
400	ValidationError | ApiError	The JSON body failed schema validation (ValidationError), or the request named no active organization (ApiError).
401	ApiError	No valid session or API key.
403	ApiError	Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

If a request fails

The response table for each operation lists its documented errors. Common status codes include:

• 400 — the body failed schema validation, or the request named no active organization. A ValidationError body carries the failing fields; an ApiError body carries only error.
• 401 — no valid session or API key.
• 403 — authenticated, but not a member of the named organization, or a client collaborator without the required access.
• 404 — check the resource ID and your access to the selected Workspace.
• 409 — the expected revision or state is stale, or another operation currently owns the transition.
• 500 — the operation failed server-side. Retry only where an idempotency key makes that safe.

Next steps

API reference

Browse endpoints, request fields and responses.

API & OpenAPI

Download the contract, generate a client, and read the compatibility policy.

TypeScript SDK

Auth, retries, typed errors, uploads and streaming, already built.

CLI reference

The same operations from a terminal, with a stable JSON envelope.