---
title: "Import your agents"
method: POST
path: "/agent-imports"
tags: ["Imports"]
---

# Import your agents

`POST /agent-imports`

## Request

- Base URL: `https://api.ando.so/v1`
- URL: `https://api.ando.so/v1/agent-imports`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Brings the agents you own in Buzz into Ando as agents you created. Any full workspace member can run it: it writes no messages, conversations, or other people. Requires an API key with the agents:write scope. Each agent must carry its own owner attestation naming the Buzz identity that signed owner_proof; others are skipped. Running it again returns agents you already imported.

## Request body

- CreateAgentImportBody: Brings agents you own in another tool into Ando as agents you created. Each attestation is an event signed by the agent's key carrying exactly one NIP-OA `auth` tag naming the owner. owner_proof is a fresh event (within 10 minutes) signed by that owner's key, of kind 27235, with tags `["u", "ando:agent-import"]`, `["method", "POST"]` and `["ando_key", <SHA-256 hex of the API key sending the request>]`.
  - `agents` AgentImportItem[], required: Agents to import.
    - `attestation` AgentImportSignedEvent, required: A signed Nostr event (NIP-01).
      - `content` string, required: Event content.
      - `created_at` integer, required: Unix seconds.
      - `id` string, required: Event id: SHA-256 of the canonical serialization, hex.
      - `kind` integer, required: Event kind.
      - `pubkey` string, required: Signing public key, 64 hex characters.
      - `sig` string, required: BIP-340 Schnorr signature, 128 hex characters.
      - `tags` array[], required: Event tags.
        - string[]: One tag.
    - `display_name` string, required: The agent's name.
    - `model` string, nullable, required: The agent's model in the source tool. Unknown models use Ando's default.
    - `provider` string, nullable, required: The model's provider, e.g. anthropic.
    - `response_scope` 'workspace' | 'personal', required: Whom the agent answers: everyone, or only you.
    - `system_prompt` string, required: The agent's instructions; may be empty.
  - `owner_proof` AgentImportSignedEvent, required: A signed Nostr event (NIP-01).
    - `content` string, required: Event content.
    - `created_at` integer, required: Unix seconds.
    - `id` string, required: Event id: SHA-256 of the canonical serialization, hex.
    - `kind` integer, required: Event kind.
    - `pubkey` string, required: Signing public key, 64 hex characters.
    - `sig` string, required: BIP-340 Schnorr signature, 128 hex characters.
    - `tags` array[], required: Event tags.
      - string[]: One tag.
  - `source` 'buzz', required: The tool the agents come from.
  - `source_workspace_id` string, required: The Buzz relay host, the same id a history import of it uses.

## Response `200`

Per-agent outcomes.

- AgentImportResponse: Agent import response.
  - `data` object, required: Per-agent outcomes, in request order.
    - `agents` AgentImportResultItem[], required: Outcomes.
      - `agent_id` string, nullable, required: The Ando agent, unless skipped.
      - `external_id` string, required: The agent's pubkey in the source tool.
      - `outcome` 'created' | 'existing' | 'skipped', required: created, existing (imported by you before), or skipped.
      - `reason` 'not_your_agent' | 'imported_by_someone_else' | 'linked_to_a_person' | 'name_taken', nullable, required: Why it was skipped.

## Other responses

- `400`: Bad request.
- `401`: Missing or invalid API key.
- `403`: Forbidden.
- `404`: Not found.
- `409`: Conflict.
- `429`: Rate limit or quota exceeded.
- `500`: Internal server error.

## Changes

- **2026-10-20** `cdcd5ee83d31`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ando/apis/ando-public-api/changes/agent-imports/post.md)

---

[API](https://skmtc.dev/ando/apis/ando-public-api.md) - [All operations](https://skmtc.dev/ando/apis/ando-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ando/apis/ando-public-api/revisions/d852746d81c2?raw)