Skip to main content
POST
Register Agent

Register Agent

POST /v1/agents Registers a new machine agent identity for the authenticated tenant. The platform generates an Ed25519 key pair for the agent, assigns a MAIP-compliant agent ID, and records the initial key in the key history ledger. Newly registered agents start with active status and an initial trust score of 0.500.
The number of agents you can register depends on your billing plan. If you exceed your plan limit, the API returns 402 Payment Required. Contact sales for enterprise-tier agent limits.

Authentication

Requires X-API-Key header or Bearer JWT token. Tenant-scoped via X-Tenant-ID.

Request Body

string
required
The type of machine agent being registered. Determines default behavior and audit categorization. One of: "orchestrator", "worker", "inference", "pipeline", "service", "bot", "llm". Defaults to "worker" if omitted.
string
required
Human-readable name for the agent. Used in dashboards, audit logs, and alert notifications. Maximum 256 characters.
string
Detailed description of the agent’s purpose, capabilities, or operational context. Maximum 2048 characters.
string[]
List of permission scopes granted to the agent. Uses resource:action format (e.g., "data:read", "tool:execute", "model:train"). Use resource:* for wildcard access. Prefix with ! to explicitly deny (e.g., "!data:delete"). Defaults to an empty array if omitted.
object
Arbitrary key-value metadata attached to the agent. Useful for tagging, cost allocation, or integration-specific context. Maximum 16 KB serialized.
string
ISO 8601 timestamp for automatic agent expiration. When reached, the agent transitions to revoked status. Omit for non-expiring agents.

Response

string
Internal UUID primary key.
string
MAIP-compliant agent identifier in format maip:<tenant8>:<ulid>. Use this value in all subsequent API calls referencing this agent.
string
UUID of the owning tenant.
string
The registered agent type.
string
Human-readable agent name.
string
Agent description, if provided.
string
Initial trust level. Newly registered agents start at "authenticated".
number
Numeric trust score (0.0 to 1.0). Newly registered agents start at 0.500.
string
Agent lifecycle status. Always "active" on creation.
string
Base64url-encoded Ed25519 public key generated for this agent. Store this securely for signature verification.
string
Unique identifier for the agent’s signing key. Referenced in receipts and attestations.
string[]
The effective scopes assigned to the agent.
object
The metadata object, if provided.
number
Current delegation chain depth. Always 0 for directly registered agents. Maximum depth is 8 per MAIP protocol.
string
UUID of the user who registered the agent, if authenticated via user token.
string
Expiration timestamp, if set.
string
ISO 8601 creation timestamp.
string
ISO 8601 last-updated timestamp.

Example

Authorizations

X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
agent_type
enum<string>
required

Classification of the agent

Available options:
orchestrator,
worker,
inference,
pipeline,
service,
bot,
llm
display_name
string
required

Human-readable agent name

Maximum string length: 256
description
string

Free-text description of the agent purpose

scopes
string[]

Permission scopes granted to the agent

metadata
object

Arbitrary key-value metadata

Response

Agent registered

id
string<uuid>
agent_type
enum<string>
Available options:
orchestrator,
worker,
inference,
pipeline,
service,
bot,
llm
display_name
string
Maximum string length: 256
description
string
status
enum<string>
Available options:
active,
suspended,
revoked
scopes
string[]
metadata
object
trust_score
number<float>
Required range: 0 <= x <= 1
public_key
string

Base64-encoded public key

session_count
integer
keys
object[]
created_at
string<date-time>
updated_at
string<date-time>