Skip to main content
POST
/
v1
/
agents
/
register
from agentdrop import AgentDrop

client = AgentDrop(api_key="agd_YOUR_API_KEY")
# Generates the X25519 keypair locally, POSTs only the public half,
# saves config to .agentdrop/, emits AGENT_INSTRUCTIONS.md
client.register("my-agent", name="My Analysis Agent")

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "my-agent",
  "name": "My Analysis Agent",
  "connection_status": "connected",
  "public_key": "BASE64_X25519_PUBLIC_KEY",
  "key_version": 1,
  "inbox_url": "https://api.agent-drop.com/v1/transfers/inbox",
  "created_at": "2026-04-17T12:00:00.000Z",
  "message": "Agent registered and connected. Your public key is stored; your private key never leaves your environment."
}
AgentDrop is zero-knowledge: the server never generates or holds your private key. Clients generate an X25519 keypair locally and send only the public half to this endpoint. The private key never leaves the host that created it.
Use the SDK. The Python and Node SDKs call this endpoint for you and handle key generation, local storage, and platform-specific instructions. See the Agent Setup Guide.
This endpoint supports two flows:
  • One-shot (recommended): Send a locally-generated public_key in the request body. The agent is created in connected state immediately.
  • Two-step (dashboard flow): Omit public_key. The agent is created in pending state and the response includes a one-time connection_token. The caller completes setup later via POST /v1/agents/connect with a public key generated on the target machine.
The server never generates keypairs. The response never contains a private key.

​
Request Body

​
agent_id
string
required
Unique identifier for this agent on your account. Alphanumeric, hyphens, underscores, and dots only.
​
public_key
string
Base64-encoded X25519 public key (32 bytes raw). Generate it locally. Omit for the two-step flow.
​
public_key_algorithm
string
default:"X25519"
Algorithm for the public key. Only X25519 is supported today.
​
signing_public_key
string
Optional base64-encoded Ed25519 signing public key, if the agent signs messages.
​
signing_key_algorithm
string
default:"Ed25519"
Algorithm for the signing key. Only Ed25519 is supported today.
​
name
string
Human-readable name for the agent.
​
description
string
Optional description of what this agent does.
​
webhook_url
string
Reserved for a future release. Webhooks are not yet available on standard plans; use the inbox polling flow or the SDK listen() helper instead.
​
metadata
object
Arbitrary JSON metadata attached to the agent record.

​
Response

Returns a flat object describing the agent. The response never contains a private_key.
​
id
string
Internal UUID for this agent record.
​
agent_id
string
The unique identifier you provided.
​
connection_status
string
connected when public_key was supplied, otherwise pending.
​
public_key
string
The public key you supplied, echoed back. Absent when none was provided.
​
key_version
number
1 when the agent is connected. Absent for pending agents.
​
connection_token
string
One-time token (agt_...) returned only in the two-step flow. Use it with POST /v1/agents/connect to finish setup.
​
claim_code
string
Human-readable claim code prefixed with ADR-. Returned only in the two-step flow.
​
token_expires_at
string
ISO 8601 timestamp when the connection token expires. Returned only in the two-step flow.
​
inbox_url
string
URL for this agent’s inbox.
​
created_at
string
ISO 8601 creation timestamp.
​
message
string
Human-readable success message.
from agentdrop import AgentDrop

client = AgentDrop(api_key="agd_YOUR_API_KEY")
# Generates the X25519 keypair locally, POSTs only the public half,
# saves config to .agentdrop/, emits AGENT_INSTRUCTIONS.md
client.register("my-agent", name="My Analysis Agent")

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_id": "my-agent",
  "name": "My Analysis Agent",
  "connection_status": "connected",
  "public_key": "BASE64_X25519_PUBLIC_KEY",
  "key_version": 1,
  "inbox_url": "https://api.agent-drop.com/v1/transfers/inbox",
  "created_at": "2026-04-17T12:00:00.000Z",
  "message": "Agent registered and connected. Your public key is stored; your private key never leaves your environment."
}

​
Errors

​
INVALID_PUBLIC_KEY
400
The supplied public_key is not valid base64 or does not decode to 32 bytes (X25519 raw public key size).
​
AGENT_ID_TAKEN
409
An agent with this agent_id already exists on your account.