Skip to main content
POST
Import an agent export file

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

Idempotency-Key
string

Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.

Required string length: 1 - 256
Pattern: ^[!-~]+$
x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Body

application/json

An agent export file to import into the calling organization, with where each of its references lands.

file
object | null
required
write-only

A recursion.agent-export document as the console's Export writes it, format version 1 or 2. Version 2 carries catalog skills whole, with their bundled files. The file is at most 33554432 bytes.

choices
object
write-only

Where each item of the preview lands, by its key: the id of one of its candidates, or an empty string to leave it out. An item not named here takes its default: its only candidate when it has exactly one, otherwise nothing. A skill item defaults to importing the file's own copy, and a catalog skill item to creating the skill.

name
string
write-only

Name for the new agent. Omit to keep the name in the file.

Maximum string length: 256

Response

Created

agentId
string
required
read-only

Id of the new agent.

agentVersionId
string
required
read-only

Id of its first version.

createdSkills
object[]
required
read-only

Catalog skills the import created, in the order the agent lists them.

report
object
required
read-only