---
title: "Public Import Agent"
method: POST
path: "/v1/agents/import"
tags: ["V1 - Agents (Co-workers)"]
---

# Public Import Agent

`POST /v1/agents/import`

## Request

- Base URL: `https://api.app.noxus.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.app.noxus.ai/v1/agents/import`
- Auth: API key in header `X-API-Key`

## Query parameters

- `mode` 'version' | 'clone' | 'replace': Operator control over how a bundle's artifacts land in the target. - ``version``: keep the bundle's IDs. If the artifact already exists in the target workspace, append a new version row (Workflow/Assistant) or refuse with NOT_VERSIONABLE (KB/Inbox — use ``replace``). If not, create with the bundle's id. Lineage history is appended on every successful artifact write. - ``clone``: today's default — fresh UUIDs everywhere, no history. - ``replace``: keep IDs, overwrite the active definition in place. No version row. Lineage history is appended.
- `activate` boolean
- `on_missing_dependency` 'fail' | 'warn'
- `dry_run` boolean

## Request body

- ImportAgentRequest
  - `definition` string, required
  - `version` 'auto' | 'v3' | 'v4': Wire format for an export/import payload. - ``auto`` (default both directions): export emits the default format (currently ``v3`` base64, for back-compat with existing pipelines); import detects the format from the payload content. - ``v4``: plaintext multi-doc YAML (`.nx`) — opt-in, requested on purpose. - ``v3``: legacy base64-encoded bundle.

## Response `200`

Successful Response

- ExportableReference[]
  - `reference` string, required
  - `type` 'kb' | 'workflow' | 'assistant' | 'file' | 'inbox' | 'connection' | 'secret' | 'deployment' | 'table' | 'trigger', required
  - `version` string, nullable
  - `name` string, nullable
  - `icon` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/noxus/apis/noxus-backend.md) - [All operations](https://skmtc.dev/noxus/apis/noxus-backend/llms.txt) - [OpenAPI document](https://skmtc.dev/noxus/apis/noxus-backend/revisions/0e37810b7ad5?raw)